Working Group Draft 10 September 2009
This version:
http://www.daisy.org/projects/daisy-online-delivery/drafts/20090910/do-spec-20090910.html
This version as a zip archive:
http://www.daisy.org/projects/daisy-online-delivery/drafts/20090910/do-spec-20090910.zip
Previous version:
http://daisy-online-delivery.googlecode.com/files/do-draft-20090828.zip
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.
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
List of Examples
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.
The 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.
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.
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.
A resource made available by a Service Provider through a Service, such as a DAISY Digital Talking Book.
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.
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).
Transfer of Content from the Service to the Reading System, which the Reading System stores in non-volatile memory.
Download and Streaming are Reading System behaviors, not aspects of this protocol.
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.
A [WSDL 1.1] port type. A set of Operations supported by the Service.
Grant access to Content. A Reading System uses the
issueContent
operation to request access from the Service.
A [WSDL 1.1] operation. An action supported by the Service.
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.
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.
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.
A web service that implements the DAISY Online Delivery Protocol. Corresponds to a [WS-I Basic Profile 1.1 Conformance Targets] instance.
A file hosting server that is not under the control of the Service Provider.
The person(s) or organization(s) who own a Service.
The Service Provider may not be the same entity who owns the servers the Service runs on.
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].
Transfer of Content from the Service to the Reading System, which the Reading System renders immediately and stores only temporarily.
Download and Streaming are Reading System behaviors, not aspects of this protocol.
A person who interacts with a Service using a Reading System and/or or accesses Content from the Service.
This section is normative
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.
Services and 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].
An established HTTP session is not in itself a valid indicator that a Reading System has successfully logged on to the Service (see 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.
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.
The use of HTTPS for all transactions with a Service is recommended as the data being exchanged may contain confidential information. HTTPS also allows a Reading System to verify the identity of the Service through the use of certificates.
It is recommended when implementing HTTPS that all certificates be registered with a certificate authority and not be self-signed.
All URIs that identify resources served over HTTPS must use the standard URI
prefix https:.
A compliant Reading System must support HTTPS. Support for HTTPS is recommended for Services.
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
[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.
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.
HTTP Basic Authentication credentials must not be used to log on to a Service. For authenticating a SOAP session, see Section 3.1.1, “HTTP Cookies”.
A compliant Reading System must support Basic Authentication. Service support for Basic Authentication is recommended.
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.
The DAISY Online Delivery protocol is compliant with the requirements of [WS-I Basic Profile 1.1]. All conformant implementations of this protocol must also be compliant with [WS-I Basic Profile 1.1].
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.
This section is normative
The DAISY Online Delivery protocol supports two basic service models:
A Service may offer Borrowable Content, Purchasable Content or both.
To provide Content under both service models, a Service Provider must supply two Content items with different Content Identifiers. The Content items may point to 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
Provider must not change the value of the requiresReturn
attribute.
Services offering Borrowable Content must:
implement the
returnContent
operation; and
offer the issued
contentList
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.
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.
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
.
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 specifc 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.
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.
Service Providers should use the expired
contentList
with caution. Users should be notified that Content has expired
and will be deleted.
The following conditions apply to any item of Purchasable Content:
the requiresReturn attribute of the
Content's
contentMetadata
type must be set to false;
if issued, the Content item
may be listed in the User's issued
contentList but should not
be listed in the expired
contentList.
The Reading System must not call
returnContent
with a Content Identifier of a Content item whose
contentMetadata
type's requiresReturn attribute
is false.
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.
The following steps must be followed when starting a Session to authenticate a Reading System to a Service:
The Reading System must pass the User's login credentials to
the Service by calling the
logOn
operation.
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.
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.
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:
The
getServiceAttributes
operation must be called to discover necessary information
about the Service.
The
setReadingSystemAttributes
operation must be called to provide information about the
Reading System's capabilities to the Service. The Service
must respond to this operation call with a return value of 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.
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.
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.
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 valid.
The DAISY Online Delivery protocol supports two content selection methods:
A Service Provider must offer Users at least one content selection method.
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.
A Service offering the Out-of-band Content Selection Method is compliant if it:
provides one or more out-of-band mechanisms for the selection/assignment of Content;
declares support for the Out-of-band
Content Selection Method in the
supportedContentSelectionMethods
service attribute; and
exposes the selected Content to the Users' Reading System(s)
through the
getContentList
operation when the operation is invoked with the
id
parameter set to the value new.
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.
A Service offering the Browse Content Selection Method is compliant if it:
provides support for the Dynamic Menus protocol feature; and
declares support for the Browse Content
Selection Method in the
supportedContentSelectionMethods
service attribute.
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.
In order to download Content from a Service, a Reading System must first invoke the following Operations in the given sequence.
A Reading System must retrieve a contentList from a Service using one of the methods described in Content Selection Methods prior to requesting that the Service issue any items.
All of the Operations identified in this section take a Content Identifier as a parameter.
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.
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.
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.
This protocol does not specify the Reading System behaviors that
occur when a Service does not return a true value.
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.
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.
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.
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.
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.
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. See Section 3.1.3, “HTTP Basic Authentication”.
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.
The functionality detailed in this section can also be used to publish installments by progressively updating the same Content item.
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.
If a Reading System supports PDTB2, it should
inform a Service by including a
supportedContentProtectionFormats
attribute 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.
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.
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….
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.
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.
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.
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.
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.
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.
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.
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.
[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.
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.
[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.
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.
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.
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.
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.
Every dynamic menu system must have a root question. The root question corresponds to a main menu in that it is the base starting point for rendering menu options to a User.
A Reading System must use the reserved value default as the
userResponse
questionID the first time that it invokes the
getQuestions
operation. The default value alerts the
Service that the root question is being requested.
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.5, “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.4, “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.
Except at menu end points, a Reading System must invoke the getQuestions operation to get the next set of
questions to display.
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.
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.
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 label ; or
a contentListRef containing the ID of a contentList .
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.
A response containing an input or multiple choice question never represents an end point.
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. See Section 4.7.1, “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.
This section is normative
This section documents the protocol operations that a Service unconditionally must support.
logOn
Operation Logs the Reading System on to the Service.
Type: xs:string [XML Schema 2]
The user ID
Type: xs:string [XML Schema 2]
The user password
Type: xs:boolean [XML Schema 2]
Specifies whether the log-on was successful
logOff Operation Logs the Reading System off the Service.
A return value of false or an issued fault both
indicate that the operation was not succesful.
The logOff operation has no parameters.
Type: xs:boolean [XML Schema 2]
Specifies whether the log-off was successful
setReadingSystemAttributes Operation Posts properties of the Reading System to the Service.
A Reading System must invoke this operation as part of the Session Initialization Sequence. This operation may be invoked additional times during a session to record dynamic changes in the Reading System properties.
Type: readingSystemAttributes
Contains the reading system attributes to post.
Type: xs:boolean [XML Schema 2]
Specifies whether the ReadingSystemAttributes were received successfully on the Service.
internalServerError, invalidOperation, invalidParameter, noActiveSession
issueContent Operation Requests the issuance of the specified content.
Type: xs:string [XML Schema 2]
Contains the Content Identifier of the content that this issuance request is for.
Type: xs:boolean [XML Schema 2]
Specifies whether the content was issued successfully.
internalServerError, invalidOperation, invalidParameter, noActiveSession
getContentMetadata Operation Retrieves contentMetadata for the specified content.
This operation is required in the Content Retrieval Sequence, and may also be called during other stages of a Session, as long as the Session Initialization Sequence has been successfully completed.
Type: xs:string [XML Schema 2]
Contains the Content Identifier of the content
for which metadata is being requested, as expressed by the
id attribute of the relevant
contentItem in the contentList type.
Type: contentMetadata
Contains the metadata for the specified content.
getContentResources Operation Retrieves resources for the specified content.
This operation is only valid if a previous call to issueContent with a result of
true has been made for the given content,
during the current or a previous Session.
Type: xs:string [XML Schema 2]
Contains the content identifier of the content for which resources are being requested, as defined in the [Dublin Core] identifier field of the contentMetadata type.
Type: resources
Contains the resources for the specified content.
internalServerError, invalidOperation, invalidParameter, noActiveSession
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 this operation again later in the session to retrieve information on possible changes in Service properties.
The getServiceAttributes operation has no parameters.
Type: serviceAttributes
Contains the attributes of the service.
getContentList Operation Retrieves a list of Content items.
The retrieved list can either be of a 'precomposed' type, in
which case it is referred to by passing one of the three reserved values
defined in the
id
parameter below (Refer to 4, Protocol Fundamentals for
information on in which contexts these reserved values are used).
The list can also be of a 'dynamic' type, typically being
exposed by the Service as 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 (See for example questions).
Type: xs:ID [XML Schema 2]
Specifies the identity of the list to retrieve.
The following three values are reserved, and must not be used as identifiers of contentLists except in the contexts defined below.
Refers to a list of Content that the Service currently has recorded as issued (see issueContent) to the User.
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 expired.
Services that provide Borrowable Content must recognize this identifier.
Refers to a list of Content that the Service offers to issue to the User.
The list excludes all Content that is issued.
Services that support the Out-of-band Content Selection Method must recognize this identifier.
Refers to a list of Content that has been issued to the User, but has expired.
Type: xs:integer [XML Schema 2]
When retrieving a subset of the contentList,
contains the first item in the subset to retrieve. The first
item in the list has the index 0.
Type: xs:integer [XML Schema 2]
When retrieving a subset of the 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.
Type: contentList
Contains the requested content list, or a segment thereof.
The value of the id attribute on the
returned contentList must match the value of
the
id
parameter passed with the getContentList
operation.
internalServerError, invalidOperation, invalidParameter, noActiveSession
This section documents the protocol operations that a Service may support. Refer to Content Selection Methods for conditions when certain of these optional operations become required.
getServiceAnnouncements Operation Retrieves the announcements awaiting the User's attention from the Service.
This operation has no parameters.
Type: announcements
Contains the announcements from the Service.
internalServerError, invalidOperation, operationNotSupported, noActiveSession
markAnnouncementsAsRead Operation Marks the specified announcements as read.
This operation is only valid if a previous call to getServiceAnnouncements has been made during the session.
Type: read
Contains the announcements to mark as read, expressed as references to the announcement's ID values as specified in the announcements type.
Type: xs:boolean [XML Schema 2]
Specifies whether the specified announcements were successfully marked as read on the Service
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
returnContent Operation Notify the Service that the specified content has been deleted
from the Reading System. A successful invocation of this operation (e.g. a
return value of true from the Service) means that
the Content is no longer issued to the User.
A Reading System should not call returnContent
where the contentMetadata's requiresReturn attribute is not true.
A Reading System must delete the content before calling returnContent. A Reading System must not call returnContent on Content it never had.
This protocol cannot guarantee that a Reading System has actually deleted
the content before calling returnContent. If a
Service receives a call to this operation, that does not constitute proof
that the content has been removed. If a Service Provider requires a robust
copy prevention mechanism, it should employ a DRM solution such as [PDTB2].
Type: xs:string [XML Schema 2]
Specifies the Content Identifier of the content that this return request is for.
Type: xs:boolean [XML Schema 2]
Specifies whether the content was returned successfully.
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
setBookmarks Operation Request the storage of bookmarks for a content item to the Service.
Note that this operation only supports the storage of bookmarks for one content item at a time.
Type: xs:string [XML Schema 2]
Contains the Content Identifier for the content with which the bookmarks are associated
Type: bookmarkSet
Contains the bookmarks to store
Type: xs:boolean [XML Schema 2]
Specifies whether the bookmarks for the content were saved successfully on the Service.
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
getBookmarks Operation Retrieves bookmarks for a content item from the Service.
Type: xs:string [XML Schema 2]
Contains the Content Identifier of the content for which bookmarks are being retrieved
Type: bookmarkSet
Contains the bookmarks for the content.
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
getQuestions Operation Retrieves a question from the series of questions that comprise the Service's Menu System.
Type: userResponses
Contains the user's response to a
previous question, or, as defined in userResponse, one of the three reserved IDs: default, search or back.
Type: questions
Contains one or more multiple choice or input questions. It may also contain a Label or contentListRef child elements.
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
getKeyExchangeObject Operation Requests a [PDTB2] Key Exchange Object from the Service.
Type: keyRing
The identifiers of the keys on the Reading System's keyring.
Type: xs:string [XML Schema 2]
The identifier of the requested key.
Type: KeyExchange
A [PDTB2] Key Exchange Object, containing the requested key encrypted using one of the keys identified in keyRing.
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
Condition: an internal server error occurred on the Service and the execution of the operation was halted.
This fault is issued when errors occur that are not described by the invalidOperation, invalidParameter, operationNotSupported and noActiveSession faults. At the event of this fault being issued, Reading Systems may attempt to reinvoke the operation that failed.
Condition: the invoked operation is not valid in the current context
This fault is issued when a Reading System during an active Session invokes an operation at a stage when the invocation of another operation, or a set of other operations, is required.
Condition: an invalid parameter was passed with the operation request.
This fault is issued when a Reading System passes a parameter with an operation invocation that the Service does not recognize, allow, or support.
Condition: the invoked operation is not supported by the Service.
This fault is issued when a Reading System invokes an optional operation that the Service does not support.
Condition: the invoked operation is not allowed when there is no active session.
This fault is issued on all operation invocations except those in the operation sequence defined by the Session Initialization Sequence when a Session has either expired or not been successfully initialized.
This section is normative
The following simplified set of SGML syntax rules has been used throughout this section to define the content models for each type and element:
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.
A set of Service announcements.
getServiceAnnouncements
(response)
( announcement * )
Example 6.1. announcements
<announcements xmlns="http://www.daisy.org/ns/daisy-online/">
<announcement id="downtime" priority="1" type="WARNING">
<label xml:lang="en">
<text>The Service will not be available on friday the 11th of September due to
maintenance.</text>
<audio uri="http://example.com/content/messages/current.mp3" rangeBegin="0" rangeEnd="65856"
size="65856"/>
</label>
</announcement>
<announcement id="survey" priority="2" type="INFORMATION">
<label xml:lang="en">
<text>A new survey is available, fill it in online at our home page, or use your Daisy Online
Reading System if it has the required capabilities. Chance to win a Phantom Pocket
Reader!</text>
<audio uri="http://example.com/content/messages/current.mp3" rangeBegin="65857" size="92112"/>
</label>
</announcement>
</announcements>
A list of content items, presented by the Service to the Reading System.
getContentList
(response)
( label ?, contentItem * )
totalItems
The total number of content items exposed by the Service at this stage of the session. This instance of contentList may only contain a subset of the total number of items, e.g. it may be segmented. If the contentList is not segmented, the value of this attribute is equal to the number of contentItem children of this contentList element.
Use: required
Data type: xs:integer
firstItem
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 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 this contentList.
If this contentList is being returned on an invocation 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 id attribute must echo the passed
value, e.g. 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 arbitrary contentList identities for the duration of a Session. Services must not expose multiple arbitrary contentLists with same id during the same session.
Use: required
Data type: xs:ID
Example 6.2. A complete contentList type using bimodal labels
This example shows a contentList type that is
not segmented (the firstItem and lastItem attributes are missing on the root
element).
<contentList xmlns="http://www.daisy.org/ns/daisy-online/"
id="cl123" totalItems="2">
<label xml:lang="en">
<text>Please select from these publications.</text>
<audio uri="http://example.com/static/PleaseChooseFrom.mp3" size="12342"/>
</label>
<contentItem id="com-example-001">
<label xml:lang="en">
<text>Harry Potter and the Chamber of Secrets</text>
<audio uri="http://example.com/content/titles/hp_cs.mp3" size="130821"/>
</label>
</contentItem>
<contentItem id="com-example-002">
<label xml:lang="en">
<text>Harry Potter and the Goblets of Fire</text>
<audio uri="http://example.com/content/titles/hp_gf.mp3" size="130821"/>
</label>
</contentItem>
</contentList>
Example 6.3. A segmented contentList type
This example shows a contentList type that is
segmented (firstItem and lastItem attributes specify which of the items are included in
this segment).
<contentList xmlns="http://www.daisy.org/ns/daisy-online/"
id="cl125" firstItem="0" lastItem="1" totalItems="25">
<label xml:lang="en">
<text>Please select from these publications.</text>
</label>
<contentItem id="com-example-001">
<label xml:lang="en">
<text>Harry Potter and the Chamber of Secrets</text>
</label>
</contentItem>
<contentItem id="com-example-002">
<label xml:lang="en">
<text>Harry Potter and the Goblets of Fire</text>
</label>
</contentItem>
</contentList>
Specifies metadata about a singular piece of content.
getContentMetadata
(response)
category
Specifies a publication type denomination for the Content being described.
Reading Systems may use the value provided here to categorize or sort issued Content items on behalf of the User.
Any value is allowed. The values BOOK, MAGAZINE, NEWSPAPER and OTHER are
recommended to use for those Content items whose type can be said to
match any of these terms.
Use: optional
requiresReturn
Specifies whether the Service requires this Content to be returned.
If this attribute is true, it is a contract from the Service to the Reading System that the Reading System will at some point return the content
Reading Systems should present Users with appropriate prompts if they try to return Purchasable Content.
Use: required
Data type: xs:boolean
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 valued true, and must not be present when the requiresReturn attribute is valued false.
Use: optional
Data type: xs:dateTime
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>
getKeyExchangeObject
(response)
( Issuer , ( ds:KeyInfo | Keys )+ )
A list of key names.
getKeyExchangeObject
(parameter)
( item * )
A sequence of questions, asked by the Service to the User.
The questions element must contain either exactly one contentListRef or exactly one label or any number of multipleChoiceQuestion and or inputQuestion, in any order.
If the questions element contains a contentListRef or a label child element, the Reading system is not required to call the getQuestions operation as these child elements signify a logical end to the sequence of questions that comprise a dynamic menu.
For informative examples on the usage of the questions type, refer to [Dynamic Menus Primer].
getQuestions
(response)
( ( multipleChoiceQuestion | inputQuestion )+ | contentListRef | label )
A list of references to IDs on announcements.
markAnnouncementsAsRead
(parameter)
( item * )
Specifies Reading System properties.
The properties specified are valid no longer than for the duration of one Session.
setReadingSystemAttributes
(parameter)
( manufacturer , model , serialNumber ?, version , config )
This element is extensible.
Example 6.5. readingSystemAttributes type for a typical portable audio-centric Reading System
This example shows a readingSystemAttributes type that contains the properties that would typically be returned by small portabe audio-centric Reading System (single format support, numeric input, no text-to-speech capabilities with PDTB2 support).
<readingSystemAttributes xmlns="http://www.daisy.org/ns/daisy-online/">
<manufacturer>ACME Corporation</manufacturer>
<model>Pocket Phantom</model>
<serialNumber>123456</serialNumber>
<version>1.23</version>
<config>
<supportsMultipleSelections>false</supportsMultipleSelections>
<preferredUILanguage>en</preferredUILanguage>
<bandwidth>8000000</bandwidth>
<supportedContentFormats>
<contentFormat>ANSI/NISO Z39.86-2005</contentFormat>
</supportedContentFormats>
<supportedContentProtectionFormats>
<protectionFormat>PDTB2</protectionFormat>
</supportedContentProtectionFormats>
<supportedMimeTypes>
<mimeType type="audio/mpeg"/>
</supportedMimeTypes>
<supportedInputTypes>
<input type="TEXT_NUMERIC" xml:lang="en"/>
</supportedInputTypes>
<requiresAudioLabels>true</requiresAudioLabels>
</config>
</readingSystemAttributes>
Example 6.6. readingSystemAttributes type for a typical software-based Reading System
This example shows a readingSystemAttributes type that contains the properties that would typically be returned by a hardware- or software-based Reading System (multi-format support, full keyboard input, built-in text-to-speech capabilities but in this case no PDTB2 support).
<readingSystemAttributes xmlns="http://www.daisy.org/ns/daisy-online/">
<manufacturer>ACME Corporation</manufacturer>
<model>Pro Phantom III</model>
<serialNumber>64321</serialNumber>
<version>1.23</version>
<config>
<supportsMultipleSelections>true</supportsMultipleSelections>
<preferredUILanguage>en</preferredUILanguage>
<supportedContentFormats>
<contentFormat>ANSI/NISO Z39.86-2005</contentFormat>
<contentFormat>Daisy 2.02</contentFormat>
</supportedContentFormats>
<supportedContentProtectionFormats />
<supportedMimeTypes>
<mimeType type="text/plain" xml:lang="en"/>
<mimeType type="audio/mpeg"/>
</supportedMimeTypes>
<supportedInputTypes>
<input type="TEXT_ALPHANUMERIC"/>
<input type="AUDIO"/>
</supportedInputTypes>
</config>
<requiresAudioLabels>false</requiresAudioLabels>
</readingSystemAttributes>
A list of all the files that constitute the Content.
getContentResources
(response)
( resource + )
Example 6.7. The resources type using script URIs
This example shows a resources type where the uri attribute refers to a script that does not expose the names of the resources.
<resources xmlns="http://www.daisy.org/ns/daisy-online/">
<resource mimeType="text/xml" size="123456"
uri="https://example.com/content/get.php?a123891"
localURI="package.opf"/>
<resource mimeType="application/x-dtbncx+xml" size="123456"
uri="https://example.com/content/get.php?a123892"
localURI="nav.ncx"/>
<resource mimeType="application/smil" size="567890"
uri="https://example.com/content/get.php?a123893"
localURI="chapter_1.smil"/>
<resource mimeType="audio/mpeg" size="123456789"
uri="https://example.com/content/get.php?a123894"
localURI="chapter_1.mp3"/>
<resource mimeType="image/jpeg" size="23456"
uri="https://example.com/content/get.php?a123895"
localURI="./images/sun001.jpg"/>
</resources>
Specifies Service properties.
The properties specified are valid no longer than for the duration of one Session.
getServiceAttributes
(response)
( serviceProvider ?, service ?, supportedContentSelectionMethods , supportsServerSideBack , supportsSearch , supportedUplinkAudioCodecs , supportsAudioLabels , supportedOptionalOperations )
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>
Encapsulates a set of User responses to Service provided questions.
For informative examples on the usage of the userResponses type, refer to [Dynamic Menus Primer].
getQuestions
(parameter)
( userResponse + )
Specifies additional content transfer protocols that are supported by the reading system, beyond the protocols that are mandated by this specification.
Content model: ( protocol + )
Parent(s): config
A Service announcement.
Content model: ( label )
Parent(s): announcements
id
The identifier of this announcement. The identifier is only valid for the duration of a Session.
Use: required
Data type: xs:ID
type
A value that indicates the nature of this announcement.
Use: optional
Enumeration:
WARNING
ERROR
INFORMATION
SYSTEM
Default Value:
INFORMATION
priority
A value that indicates the priority of this announcement. The value
1 denotes the highest priority, and
the value 3 the lowest.
Use: optional
Integer Set:
minimum value: 1
maximum value: 3
Default Value:
3
Content model: empty element
Parent(s): label
uri
Specifies the URI of the audio resource containing the label.
Use: required
Data type: xs:anyURI
rangeBegin
Specifies the audio label start point in bytes counting
from the start of the resource specified in the uri attribute. If the rangeBegin attribute is not present,
this implies a rangeBegin of 0.
Use: optional
Data type: xs:integer
rangeEnd
Specifies the audio label end point in bytes counting
from the start of the resource specified in the uri attribute. If the rangeEnd attribute is not present,
this implies a rangeEnd value set to the last byte of the resource.
Use: optional
Data type: xs:integer
size
Specifies the size (in bytes) of the label audio data.
Use: required
Data type: xs:int
An estimate of the bandwidth that the Reading System allocates for the session, expressed in kilobits per second.
Data type: xs:int
Parent(s): config
A singular codec reference, specified using a canonical identifier string as dictated by the referenced codec specification.
Data type: xs:string
Parent(s): supportedUplinkAudioCodecs
Content model: ( supportsMultipleSelections , preferredUILanguage , bandwidth ?, supportedContentFormats , supportedContentProtectionFormats , supportedMimeTypes , supportedInputTypes , requiresAudioLabels , additionalTransferProtocols ? )
Parent(s): readingSystemAttributes
A singular content item.
Content model: ( label )
Parent(s): contentList
id
The Content Identifier of the Content that this contentItem represents.
Note that this value must be identical to the value of the [Dublin Core]
identifier field in the contentMetadata of this Content item.
Use: required
Data type: xs:ID
lastModifiedDate
The last modified date of this contentItem. Contains the lastModifiedDate of the most recently modified resource in the content's resources list.
Use: optional
Data type: xs:dateTime
A reference to a contentList. The referenced contentList is retrieved by invoking
getContentList
passing the value given here as the value of that operations
id
parameter.
A contentListRef as a child of the questions element signifies a logical end to the sequence of questions that comprise a dynamic menu.
Data type: xs:ID
Parent(s): questions
Embeds the data of an audio-based User response.
Services must accept audio in the [RIFF WAVE] audio file format. Services may support additional audio file formats to be used when a Reading System posts audio, and must specify if they do so in serviceAttributes.
This specification does not allow [MTOM] encoded data in this type.
Allowed values: xs:base64Binary
Parent(s): userResponse
Content model: empty element
Parent(s): supportedInputTypes
type
Use: required
Enumeration:
TEXT_NUMERIC
The Reading System supports User input using a numeric keypad.
TEXT_ALPHANUMERIC
The Reading System supports User input using an alphanumeric keyboard.
Note: this value is a superset of TEXT_NUMERIC.
AUDIO
The Reading System supports User input using audio recording.
xml:lang
Use: optional
Content model: empty element
Parent(s): inputTypes
type
Use: required
Enumeration:
TEXT_NUMERIC
The Reading System supports User input using a numeric keypad.
Note: this value is a subset of TEXT_ALPHANUMERIC.
TEXT_ALPHANUMERIC
The Reading System supports User input using an alphanumeric keyboard.
Note: this value is a superset of TEXT_NUMERIC.
AUDIO
The Reading System supports User input using audio recording.
A singular question, asked by the Service directed to the User, requiring a textual or auditory response.
Depending on the Reading System properties (as specified by the Reading System in readingSystemAttributes, the question is asked in textual and/or auditory modalities.
Content model: ( inputTypes ?, label )
Parent(s): questions
id
Use: required
Data type: xs:ID
Specifies which input types the Service is prepared to accept as a response to a question.
Content model: ( input + )
Parent(s): inputQuestion
A multi-purpose label, containing text and optionally audio.
To achieve maximum interoperability, Services should support the provision of audio labels, as Reading Systems may require such to be provided in order to function.
Content model: ( text , audio ? )
Parent(s): announcement , choice , contentItem , contentList , inputQuestion , multipleChoiceQuestion , questions , service , serviceProvider
xml:lang
Specifies the language of the label.
Use: optional
Specifies the manufacturer of the Reading System.
Data type: xs:string
Parent(s): readingSystemAttributes
An arbitrary metadata element. Allows custom metadata and/or metadata from expression schemes other than Dublin Core.
Content model: empty element
Parent(s): metadata
name
Use: required
content
Use: required
Specifies bibliographic and other metadata about the Content.
Elements in the Dublin Core namespace are normatively defined by [Dublin Core]. Note that the value of the Dublin Core identifier element represents the Content Identifier
of the Content item being described.
Additional arbitrary metadata can be provided using the generic meta element for any expression not relating to Dublin Core.
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 signals that the content being described is protected using
means defined by [PDTB2]
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
Allowed values:
OUT_OF_BAND
This service supports the Out-of-band Content Selection Method.
BROWSE
This service supports the Browse Content Selection Method.
Parent(s): supportedContentSelectionMethods
Content model: empty element
Parent(s): supportedMimeTypes
type
A [MIME] type.
Use: required
Data type: xs:string
xml:lang
Use: optional
Specifies a model designation for the Reading System.
Data type: xs:string
Parent(s): readingSystemAttributes
Content model: ( label , choices )
Parent(s): questions
id
Use: required
Data type: xs:ID
allowMultipleSelections
Specifies whether multiple selections are allowed in the
User response to this question. The default value is false.
Use: optional
Data type: xs:boolean
Default Value:
false
In the case of audio-based content narrated by a human, the person name of the narrator.
Service providers may use the string "TTS" in this field to signal that provided audio content has been rendered using text-to-speech processors.
Data type: xs:string
Parent(s): metadata
A symbolic name for an optional operation or logical group of optional operations.
Allowed values:
SET_BOOKMARKS
Specifies that this Service supports the setBookmarks operation.
GET_BOOKMARKS
Specifies that this Service supports the getBookmarks operation.
DYNAMIC_MENUS
Specifies that this Service supports the getQuestions operation.
SERVICE_ANNOUNCEMENTS
Specifies that this Service supports the getServiceAnnouncements and markAnnouncementsAsRead operations.
PDTB2_KEY_PROVISION
Specifies that this Service supports the getKeyExchangeObject operation.
Parent(s): supportedOptionalOperations
An expression of the user's preferred language of communication with the Service.
Data type: xs:language
Parent(s): config
A singular content transfer protocol, specified using a canonical identifier string as dictated by the referenced protocol.
Data type: xs:string
Parent(s): additionalTransferProtocols
Specifies whether the Reading System requires audio labels for messages issued 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 related to the case where the Reading System requires audio labels, and a Service does not support audio labels.
Data type: xs:boolean
Parent(s): config
Content model: empty element
Parent(s): resources
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 sample of the content being described, for User consumption.
Content model: empty element
Parent(s): contentMetadata
id
An identifier of the sample.
Reading Systems may retrieve the sample by calling getContentResources with this identifier as the parameter. Reading Systems must not invoke issueContent using the ID of a sample.
Use: required
Data type: xs:string
The serial number of the Reading System, if such is available.
Data type: xs:string
Parent(s): readingSystemAttributes
Specifies the identity of the Service.
Content model: ( label ? )
Parent(s): serviceAttributes
id
A static unique identifier of the Service.
This specification does not require a specific scheme to be used when expressing this identifier. The identifier should be static (ie not change over time while the Service provider remains active), and it should be globally unique.
A recommended expression form is a hyphen-separated string consisting of a two-letter country code drawn from [ISO 3166], followed by an agency code unique within its country, followed by a Service code unique among the Services offered by the provider. For example, us-afb-onlinelLibrary.
Use: required
Data type: xs:string
Specifies the identity of the Service Provider.
Content model: ( label ? )
Parent(s): serviceAttributes
id
A static unique identifier of the Service provider.
This specification does not require a specific scheme to be used when expressing this identifier. The identifier should be static (ie not change over time while the Service provider remains active), and it should be globally unique.
A recommended expression form is a hyphen-separated string consisting of a two-letter country code drawn from [ISO 3166], followed by an agency code unique within its country. For example, us-afb.
Use: required
Data type: xs:string
The size of the content being described, expressed in bytes.
Data type: xs:int
Parent(s): metadata
Specifies which kinds of content the Reading System supports.
The content of this element follows the convention of the [Dublin Core] Format property.
Content model: ( contentFormat + )
Parent(s): config
Specifies which kinds of Content Protection (Digital Rights Management) standards the Reading System supports.
Content model: ( protectionFormat * )
Parent(s): config
Specifies which Content Selection Methods are supported by this Service. A Service must support at least one of the two methods.
Content model: ( method {1, 2} )
Parent(s): serviceAttributes
Enumerates the means of User input that the Reading System supports, including transfer of that input to the Service.
If the reading system does not support any means of input, the inputTypes element is empty.
Content model: ( input * )
Parent(s): config
Specifies which content types the Reading System supports rendering of.
The content type specification applies to transferred content as well as Service messages (label).
A Service may use this information to adapt content types offered 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.
Content model: ( mimeType * )
Parent(s): config
Specifies which (if any) of the operations that are optional per this specification are supported by the Service.
Content model: ( operation * )
Parent(s): serviceAttributes
Specifies which (if any) audio codecs is supported in userResponses in addition to the codec required to be supported by this specification.
Content model: ( codec * )
Parent(s): serviceAttributes
Specifies whether this Service supports the inclusion of of audio in labels.
A Service that specifies true in this field must
include the audio element in
all labels if the Reading
System specifies true in the requiresAudioLabels element of readingSystemAttributes.
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 the allowMultipleSelections attribute with a value of true on the multipleChoiceQuestion element to the Reading System.
Data type: xs:boolean
Parent(s): config
Specifies whether the Service supports searching of its content
collection using the dynamic menu feature of this protocol. See
also the DYNAMIC_MENUS value in supportedOptionalOperations
Data type: xs:boolean
Parent(s): serviceAttributes
Specifies whether this Service supports server-side back commands,
e.g. whether getQuestions with the reserved
parameter back is supported.
Data type: xs:boolean
Parent(s): serviceAttributes
A singular 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 type 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).
Content model: ( data ? )
Parent(s): userResponses
questionID
The ID of a question being answered.
The following three values of this attribute are reserved for use as defined below:
The value default retrieves the
root question (aka main menu) from the Service. (This value
is used to initiate a dynamic menu operation sequence, and
therefore does not reflect an answered question.)
The value search retrieves the
Search menu from the Service.
A Service is not required to support the search reserved ID to claim support
for the Dynamic Menu feature. A Service must explicitly
declare whether it supports this ID in serviceAttributes.
The value back retrieves the
previous question from the Service during a dynamic menu
operation sequence.
A Service is not required to support the back reserved ID to claim support
for the Dynamic Menu feature. A Service must explicitly
declare whether it supports this ID in serviceAttributes.
Use: required
Data type: xs:NMTOKEN
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
Specifies a version designator of the Reading System.
Data type: xs:string
Parent(s): readingSystemAttributes
[DAISY 2.02] DAISY 2.02 Specification . February 2001.
[Dublin Core] Dublin Core Metadata Element Set, Version 1.1 . January 2008.
[INFOSET] XML Information Set (Second Edition) . February 2004.
[ISO 3166] ISO 3166-1 - Codes for the representation of names of countries and their subdivisions - Part 1: Country codes .
[RFC 2119] Key words for use in RFCs to Indicate Requirement Levels, RFC 2119 . March 1997.
[RFC 2396] Uniform Resource Identifiers (URI): Generic Syntax, RFC 2396 . August 1998.
[RFC 2617] HTTP Authentication: Basic and Digest Access Authentication, RFC 2617 . June 1999.
[MIME] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types, RFC 2046 . November 1996.
[XML Schema 2] XML Schema Part 2: Datatypes Second Edition . 28 October 2004.
[HTTP 1.1] HyperText Transfer Protocol 1.1, RFC 2616 . June 1999.
[HTTP Cookies] HTTP cookies in WS-I Basic Profile 1.1 .
[Document-Literal Conformance] Child Element for Document-Literal Bindings .
[MTOM] SOAP Message Transmission Optimization Mechanism . January 2005.
[SOAP 1.1] Simple Object Access Protocol 1.1 .
[PDTB2] DAISY Protected Digital Talking Book 2 .
[RFC 2109] HTTP State Management Mechanism . February 1997.
[SSL 3.0] Secure Sockets Layer 3.0 .
[TLS 1.0] Transport Layer Security 1.0 .
[WS-I Basic Profile 1.1] WS-I Basic Profile 1.1 .
[WS-I Basic Profile 1.1 Conformance Targets] WS-I Basic Profile 1.1 Conformance Targets .
[WSDL 1.1] Web Services Definition Language 1.1 .
[Z39-86.2005] ANSI/NISO Z39-86.2005 - Specifications for the Digital Talking Book . 2005.
[Z39-86.2005-BOOKMARKS] Portable Bookmarks and Highlights (part of [Z39-86.2005]) . 2005.
[RIFF WAVE] Multimedia Programming Interface and Data Specifications 1.0 (Unofficial transcript ) . August 1991.
[Dynamic Menus Primer] DAISY Online Delivery Protocol - Dynamic Menus Primer .
[Z39-86.2002] ANSI/NISO Z39-86.2002 - Specifications for the Digital Talking Book . 2002.
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.
This appendix is informative
The following individuals were members in good standing of the DAISY Online Working Group at the time of the publication of this specification:
Hiro Fujimori , Plextor
Matt Garrish , CNIB (chief editor)
Geoff Gilmour-Taylor , CNIB
Markus Gylling ,, DAISY Consortium (co-chair)
Kenny Johar , Vision Australia (co-chair)
Jelle Martijn Kok , Solutions Radio
Simon Roy , Humanware
Nick Williamson , RNIB
The following individuals are acknowledged for their contribution, either as former members of the DAISY Online Working Group, or as individual contributors:
David Andrews , Minnesota State Services for the Blind
Neil Bernstein , NLS
Sean Brooks , CNIB
Ed Chandler , RNIB
Gerry Chevalier , HumanWare
Andrew Furlong , Vision Australia
Leon Gulikers , Dedicon
Kathy Kahl , DAISY
Dinesh Kaushal , Code Factory
Mattias Karlsson , Dolphin
Greg Kearney , Individual Supporter
George Kerscher , DAISY
Dominic Labbé , HumanWare
Clive Lansink , RNZFB
Lynn Leith , DAISY
Tatsu Nishizawa , Plextor
Peter Osborne , RNIB
James Pritchett , RFB/D
Karel Raven , Solutions Radio
Ron Stewart , Dolphin US
Marc Van der Aa , Plextor Europe
Markus Wildi , Swiss Library for the Blind