Final Draft 15 February 2010
This version:
http://www.daisy.org/projects/daisy-online-delivery/drafts/20100215/do-spec-20100215.html
This version as a zip archive:
http://www.daisy.org/projects/daisy-online-delivery/drafts/20100215/do-spec-20100215.zip
Previous versions:
http://www.daisy.org/projects/daisy-online-delivery/drafts/20090927/do-spec-20090927.html
http://www.daisy.org/projects/daisy-online-delivery/drafts/20090910/do-spec-20090910.html
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 15 April 2009, and the draft for test use that was released on 27 September 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 possible 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/support/contactus.php.
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.
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 or resources made available by a Service Provider through a Service, such as DAISY Digital Talking Books. (Singular: Content item.)
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 without charge. It includes any Content that does not require return, such as 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 or 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.
An [XML Schema 2] datatype.
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.
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 (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.
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, refer to Session Initialization Sequence.
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 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 Content's
contentMetadata
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.
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 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 during any Session 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 resources 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 specific time (for example DRM schemes like [PDTB2]).
The returnBy attribute indicates the time before which the User
should return the Content.
If it has a real-time clock, a Reading System 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.
Content on the expired contentList
is still issued.
Service Providers should use the expired
contentList only in exceptional cases. 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 must be set to
false.
If issued, the Content item
may be listed in the User's issued contentList
but must not be listed in the expired contentList.
This specification does not specify the lifetime of Purchasable Content's availability
in the issued contentList.
The Reading System must not call
returnContent
with a Content Identifier of a Content item whose contentMetadata'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. 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.
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 any action, 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 active. A Service may allow multiple concurrent connections with the same session ID.
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 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 element of its serviceAttributes; and
exposes the selected Content to the Reading System
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 element of its serviceAttributes.
The steps for a Reading System to request that 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,
if the Service Provider wishes.
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 has not been issued.
A Service should 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.
The resource type has both a uri attribute and a
localURI attribute. localURI is a local name for the
Reading System to use to reference the resource, while uri
is the location of the resource's data. This system lets a Service provide
resources with arbitrary URIs (such as those served by a script), while allowing
Reading Systems to follow internal links in a Content item,
such as in a DAISY DTB.
The localURI path is relative to the root path of the Content.
A Reading System should not use the uri attribute
to name resources locally, as the URIs may
resolve to scripts or other content delivery mechanisms.
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”.
A Reading System does not require an active Session to access Content.
This section explains how Service Providers can publish updates to their Content using this protocol.
The resources type and each
contentItem
in a contentList has an optional
lastModifiedDate attribute that indicates the last time the
Content was modified. A Reading System can use this information to determine if the
Content on the Service has
been updated since the last time it was accessed. Each
resource in the
resources list also has an optional lastModifiedDate
attribute that the Reading System may use to determine
which specific resources have been updated.
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.
This protocol does not provide any trust mechanism; there is no method for Reading Systems to provide their public keys to a Service using this protocol. Services supporting PDTB2 must use some out-of-band method to register keys from Reading System manufacturers.
There is no mechanism for expiring keys in this protocol.
If a Reading System supports
PDTB2, it should inform the Service by
including a
supportedContentProtectionFormats
element with the value PDTB2, and a
keyRing element listing the names
of the keys in its key ring, in its
readingSystemAttributes.
The key names provided can be some or
all of the public keys the Reading System supports.
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 element in the
contentMetadata
named pdtb2:specVersion with the value
2005-1.
In addition, the mimeTypes for protected resources
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 must have an Authorization Object (AO) in its resources. 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 the name of the requested key.
The Service may choose any of the keys supplied in the readingSystemAttributes 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 invalidParameter fault.
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 to a User's Reading System. A service announcement is a short message in text and/or audio format that conveys information, such as an alert about expected Service down time or a warning 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.
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 announcement IDs 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 announcements to a User, a Reading System may 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 with the setBookmarks
operation. This operation can also be used by Reading Systems to record the last reading position for a
Content item. Reading Systems can
retrieve stored bookmarks with the getBookmarks operation.
Services can
also predefine bookmarks for the User to access.
[Z39-86.2005-BOOKMARKS] constitutes the normative reference
regarding the use and semantics of this type. However, audio notes are
not supported in the setBookmarks
and getBookmarks operations in this version of the protocol.
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
element of the bookmarkSet to store the User's last reading position. The Reading System should check for a last reading position
before resuming playback.
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.
This section is informative
The DAISY Online Delivery protocol offers the ability for Services to provide dynamic menus to compliant Reading Systems. Users can use these menus to perform a wide variety of activities that may be offered by the Service, such as browsing the Service's catalog, answering surveys, or purchasing items from an online store.
These sections describe the basic principles of dynamic menu systems. Refer to [Dynamic Menus Primer] for informative usage examples.
This section is normative
To support dynamic menus, a Reading System or Service must
implement the getQuestions operation.
To indicate that a Service supports dynamic menus, the
Service must include an
operation
element with the value DYNAMIC_MENUS in its
serviceAttributes.
A Reading System that supports dynamic menus must declare which input types it supports in its readingSystemAttributes. A Service should not send any question which requires an input type not supported by the Reading System. If the Reading System declares no input types, then the Service should only send multipleChoiceQuestions.
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 may support dynamic menus for other interaction purposes, but are not required to.
This section is normative
Every dynamic menu system must have a root question. The root question
is the base starting menu, or main menu. It has an id of default.
The first call to getQuestions in a
Session must be with a single
userResponse whose questionID
is default, to retrieve the root question.
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:
userResponses. The userResponses type either contains a response to
a previous question(s) or has 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 element.
This section is normative
The DAISY Online Delivery protocol defines two types of questions for navigating a menu system:
Multiple choice questions are a set of options to pick from. A multiple choice question is represented by a multipleChoiceQuestion child element of the questions type.
Input questions allow the User to respond 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 in the inputTypes child element of the inputQuestion type. Multiple input types means that any one of the types specified may be used.
This section is normative
A response to a call of getQuestions
of a questions element containing one of the following
as its child indicates an end point of the menu sequence:
a label, which can provide an informative or concluding statement for the User, such as confirmation of a purchase or thanks for completing a survey; or
a contentListRef containing the ID of a contentList, 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 is not an end point.
This section is normative
There are three reserved question identifier values:
defaultIndicates that the Reading System is requesting the root question. Refer to Section 4.7.2, “Root Question”.
searchIndicates that the Reading System is requesting the search menu.
A Service must explicitly declare whether or not it supports this value with the supportsSearch element of its serviceAttributes.
backIndicates that the Reading System has requested to step back one menu in the sequence.
A Service must explicitly declare whether or not it supports this value with the supportsServerSideBack element of its serviceAttributes.
Reading Systems that support dynamic menus must support
the default value; search and
back are optional.
This section is normative
This section documents the protocol operations that all Services must support.
logOn Operation
Logs a Reading System on to a Service.
Type: xs:string [XML Schema 2]
The ID used to access the Service.
Type: xs:string [XML Schema 2]
The password associated with the supplied ID.
Type: xs:boolean [XML Schema 2]
Specifies whether the logon was successful.
logOff Operation
Logs a Reading System off a Service.
A return value of false or an issued fault both
indicate that the operation was not successful.
The logOff operation has no parameters.
Type: xs:boolean [XML Schema 2]
Specifies whether the logoff was successful.
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.
Type: readingSystemAttributes
Contains the Reading System attributes.
Type: xs:boolean [XML Schema 2]
Specifies whether the Service successfully received the ReadingSystemAttributes.
internalServerError, invalidOperation, invalidParameter, noActiveSession
issueContent Operation
Requests a Service issue the specified Content.
Type: xs:string [XML Schema 2]
The Content Identifier of the Content item being requested.
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 must be called as part of the Content Retrieval Sequence.
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
contentItem in the contentList).
Type: contentMetadata
Contains the metadata for the specified Content item.
internalServerError, invalidParameter, noActiveSession, invalidOperation
getContentResources Operation
Retrieves the resources list for the specified Content.
The Content must be issued before this operation is called. If not, the Service shall respond with an invalidParameter fault.
Type: xs:string [XML Schema 2]
Contains the Content Identifier of the
Content item for which the resources list is being requested (as defined
in the [Dublin Core] identifier field
of the contentMetadata).
Type: resources
Contains the resources list for the specified Content item.
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 the operation to retrieve information on possible changes to Service properties at any other time during a Session.
The getServiceAttributes operation has no parameters.
Type: serviceAttributes
Contains the attributes of the Service.
getContentList Operation
Retrieves a list of Content items.
The list returned by the Service can be pre-composed, 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 dynamic (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 value of a previous operation. (Refer to the questions type for more information.)
Type: xs:NMTOKEN [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.
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 expired.
Services that provide Borrowable Content must recognize this identifier.
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.
Refers to a list of Content that has been issued to the User but has expired.
Type: xs:int [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.
Type: xs:int [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
firstItem to the end of
the list.
Type: contentList
Contains the requested Content list (or a segment of the list).
The value of the id attribute of the
returned contentList must match the value
of the id parameter passed to
the getContentList
operation.
internalServerError, invalidOperation, invalidParameter, noActiveSession
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.
getServiceAnnouncements Operation
Retrieves any announcements from the Service that a User has not yet read.
This operation has no parameters.
Type: announcements
Contains the announcements from the Service.
internalServerError, invalidOperation, operationNotSupported, noActiveSession
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.
Type: read
Contains the announcements to mark as read (expressed as references to the ID values specified in the announcements type).
Type: xs:boolean [XML Schema 2]
Specifies whether the announcements were successfully marked as read by the Service.
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
returnContent Operation
Notifies the Service that the specified Content has been deleted from the Reading System.
The specified Content is no longer issued to the User after a successful invocation of this operation.
A Reading System should not call this function for Content that has
a requiresReturn attribute with a
false value.
A Reading System must delete the Content before calling
returnContent. A Reading System must not call
returnContent on Content it has never
been issued.
This protocol cannot guarantee that a Reading System has actually
deleted the Content before calling returnContent.
The invocation of this operation does not constitute
proof that the Content has been removed. A DRM solution should be used
when Service Providers require a copy prevention mechanism.
Type: xs:string [XML Schema 2]
The Content Identifier of the Content item being returned.
Type: xs:boolean [XML Schema 2]
Specifies whether the Content was returned successfully.
returnContent must either return true
or a fault; it cannot return false.
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
setBookmarks Operation
Requests that a Service store the supplied bookmarks for a Content item.
This operation only supports the storage of bookmarks for one Content item at a time.
Type: xs:string [XML Schema 2]
The Content Identifier of the Content item the bookmarks are associated with.
Type: bookmarkSet
Contains the bookmarks to store.
Type: xs:boolean [XML Schema 2]
Specifies whether the Service successfully saved the bookmarks.
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
getBookmarks Operation
Retrieves the bookmarks for a Content item from a Service.
Type: xs:string [XML Schema 2]
The Content Identifier of the Content item the bookmarks are being retrieved for.
Type: bookmarkSet
Contains the bookmarks for the Content item.
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
getQuestions Operation
Retrieves a question from the series of questions that comprise the dynamic menu system.
Type: userResponses
Contains the response to a
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. May also contain a Label or contentListRef child elements.
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
getKeyExchangeObject Operation
Requests a [PDTB2] Key Exchange Object from a Service.
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 the Reading System's key ring.
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession
When a Service responds to an operation with a SOAP fault, an instance of one of the following types must be the child of the details element.
Each of these fault types has a reason child element, a string which can be used to send debugging information to the Reading System. This information should not be rendered to the User in most circumstances.
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 re-invoke 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 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).
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.
A list 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 10th 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 full or partial list of Content items.
getContentList (response)
( label?, contentItem* )
totalItemsThe total number of contentItems in the whole list.
If this is just a part of the list, then totalItems will
be greater than the number of contentItems returned; otherwise,
they will be equal.
Use: required
Data type: xs:int
firstItemThe 0-based index of the first contentItem
in this contentList within the whole list.
This attribute must be provided if this is a partial list. If this
attribute is present, the lastItem attribute must
also be present.
Use: optional
Data type: xs:int
lastItemThe 0-based index of the last contentItem
in this contentList within the whole list.
This attribute must be provided if this is a partial list. If this
attribute is present, the firstItem attribute must
also be present.
Use: optional
Data type: xs:int
idThe identifier of the contentList.
The identifier can be one of three reserved values,
new, issued or
expired, or can be an arbitrary value,
typically exposed in a contentListRef at an end point in a
dynamic menu
operation sequence.
Services should persist contentList identifiers for the duration of a Session. Services must not expose multiple contentLists with the same arbitrary identifier during the same session.
Use: required
Data type: xs:NMTOKEN
Example 6.2. A complete contentList with audio labels
This example shows a complete contentList (the
firstItem and lastItem attributes
are not present 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 Goblet of Fire</text>
<audio uri="http://example.com/content/titles/hp_gf.mp3" size="130821"/>
</label>
</contentItem>
</contentList>Example 6.3. A partial contentList
This example shows a partial contentList (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 Goblet of Fire</text>
</label>
</contentItem>
</contentList>The metadata of a Content item.
getContentMetadata (response)
categoryThe 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
requiresReturnSpecifies whether the Service requires this Content to be returned.
If this attribute is true and the Content is issued, it is a contract from the Service to the Reading System that, if the Content is issued, 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
Example 6.4. Example contentMetadata
This example shows the contentMetadata 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 sequence of questions.
The questions element must contain either:
exactly one contentListRef; or
exactly one label; or
any number of multipleChoiceQuestions and/or inputQuestions, 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 indicate that this is an endpoint to the sequence of questions that
comprise a dynamic menu.
For informative examples on the usage of the questions type, refer to the [Dynamic Menus Primer].
getQuestions (response)
( ( multipleChoiceQuestion | inputQuestion )+ | contentListRef | label )
A list of announcement identifiers.
markAnnouncementsAsRead (parameter)
( item* )
Specifies Reading System properties.
The properties specified are valid until the end of the Session.
setReadingSystemAttributes (parameter)
( manufacturer, model, serialNumber?, version, config )
This element is extensible.
Example 6.5. readingSystemAttributes for a portable audio-centric Reading System
This example shows readingSystemAttributes for a small portable audio-centric Reading System (single format support, numeric input, no text-to-speech capabilities, 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>
<keyRing>
<item>DAISY.lv-acme.ACME</item>
<item>DAISY.lv-acme.Phantom-1</item>
<item>DAISY.lv-acme.SN123456</item>
<item>DAISY.ca-qqhb.006442</item>
<item>DAISY.au-atbi.userKey-4C452DB4</item>
</keyRing>
<supportedMimeTypes>
<mimeType type="audio/mpeg"/>
</supportedMimeTypes>
<supportedInputTypes>
<input type="TEXT_NUMERIC" />
</supportedInputTypes>
<requiresAudioLabels>true</requiresAudioLabels>
</config>
</readingSystemAttributes>
Example 6.6. readingSystemAttributes for a more functional Reading System
This example shows the readingSystemAttributes for a more functional Reading System, such as a software 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 resources that constitute the Content.
getContentResources (response)
( resource+ )
returnBySpecifies 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 of this Content's contentMetadata is
true, and must not be present when that attribute is
false.
This attribute may not change value while the Content is issued.
Unlike requiresReturn, this attribute does not
constitute a contract.
Use: optional
Data type: xs:dateTime
lastModifiedDateThe last modified time of the Content item.
Use: optional
Data type: xs:dateTime
Example 6.7. A resources instance using script URIs
This example shows a resources instance 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>
Properties of the Service.
The properties specified must be constant for the duration of the Session.
getServiceAttributes (response)
( serviceProvider?, service?, supportedContentSelectionMethods, supportsServerSideBack, supportsSearch, supportedUplinkAudioCodecs, supportsAudioLabels, supportedOptionalOperations )
Example 6.8. serviceAttributes for a minimal library Service
This example shows the serviceAttributes for a Service that only supports the out-of-band Content selection method.
<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 for a fuller Service
This example shows the serviceAttributes for a Service that supports both Content Selection Methods and provides some or all of its Content protected 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>A set of User responses to questions provided by the Service.
For informative examples of the userResponses type, refer to the [Dynamic Menus Primer].
getQuestions (parameter)
( userResponse+ )
Specifies any additional transfer protocols that are supported by the Reading System, beyond HTTP and HTTPS.
Content model: ( protocol+ )
Parent(s): config
A Service announcement.
Content model: ( label )
Parent(s): announcements
idThe identifier of this announcement. This identifier is only valid for the duration of a Session.
Use: required
Data type: xs:NMTOKEN
typeA value that indicates the nature of this announcement.
Use: optional
Enumeration:
WARNING
ERROR
INFORMATION
SYSTEM
Default Value: INFORMATION
priorityThe priority of this
announcement. 1 is
the highest priority and
3 is the lowest.
Use: optional
Integer Set:
minimum value: 1
maximum value: 3
Default Value: 3
Content model: empty element
Parent(s): label
uriThe URI of the audio component of the label.
Use: required
Data type: xs:anyURI
rangeBeginThe byte offset of the start of the audio label
in the resource named in
the uri attribute. If the
rangeBegin attribute is not present, the start offset
is 0.
Use: optional
Data type: xs:long
rangeEndThe byte offset of the end of the audio label
in the resource named in
the uri attribute. If the
rangeEnd attribute is not present, the end
is the last byte of the resource.
Use: optional
Data type: xs:long
sizeThe size, in bytes, of the label's audio data.
Use: optional
Data type: xs:long
An estimate of the bandwidth that the Reading System allocates for the Session, in kilobits per second.
Data type: xs:int
Parent(s): config
Content model: ( label )
Parent(s): choices
idUse: required
Data type: xs:NMTOKEN
Content model: ( supportsMultipleSelections, preferredUILanguage, bandwidth?, supportedContentFormats, supportedContentProtectionFormats, keyRing?, supportedMimeTypes, supportedInputTypes, requiresAudioLabels, additionalTransferProtocols? )
Parent(s): readingSystemAttributes
The content of this element follows the convention
of the [Dublin Core]
Format element.
Data type: xs:string
Parent(s): supportedContentFormats
A single Content item.
Content model: ( label )
Parent(s): contentList
idThe Content Identifier of this Content item.
This value must be identical to the value of
the dc:identifier element in the contentMetadata of this Content
item.
Use: required
Data type: xs:string
lastModifiedDateThe last modified time of the Content.
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.
Data type: xs:NMTOKEN
Parent(s): questions
The base64-encoded data of an audio User response.
Services must accept audio in the [RIFF WAVE] format. Services may support additional audio formats, and must specify those formats in serviceAttributes.
Allowed values: xs:base64Binary
Parent(s): userResponse
Content model: empty element
Parent(s): inputTypes, supportedInputTypes
typeUse: required
Enumeration:
TEXT_NUMERIC
The Reading System supports numeric input.
The Service allows numeric-only responses to the question.
TEXT_ALPHANUMERIC
The Reading System supports text and numeric input.
The Service allows text and numeric responses to the question.
AUDIO
The Reading System supports audio input.
The Service allows audio responses to the question.
An input field that accepts a text or audio response.
Content model: ( inputTypes?, label )
Parent(s): questions
idUse: required
Data type: xs:NMTOKEN
Specifies which input types the Service will accept in response to the 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 them in order to render Service messages to the user.
Content model: ( text, audio? )
Parent(s): announcement, choice, contentItem, contentList, inputQuestion, multipleChoiceQuestion, questions, service, serviceProvider
xml:langThe language of the label.
Use: required
dirThe direction of the text.
Use: optional
Enumeration:
ltr
Left-to-right.
rtl
Right-to-left.
The manufacturer of the Reading System.
Data type: xs:string
Parent(s): readingSystemAttributes
An arbitrary metadata element. Allows custom metadata fields from schemes other than Dublin Core.
Content model: empty element
Parent(s): metadata
nameUse: required
contentUse: required
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]
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
typeA [MIME] type.
Use: required
Data type: xs:string
xml:langUse: optional
The model name or designation of the Reading System.
Data type: xs:string
Parent(s): readingSystemAttributes
Content model: ( label, choices )
Parent(s): questions
idUse: required
Data type: xs:NMTOKEN
allowMultipleSelectionsSpecifies 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 Content narrated by a human, the name of the narrator.
Data type: xs:string
Parent(s): metadata
One of the optional operations or groups of optional operations defined below.
Allowed values:
SET_BOOKMARKS
This Service
supports the setBookmarks
operation.
GET_BOOKMARKS
This Service
supports the getBookmarks
operation.
DYNAMIC_MENUS
This Service
supports the getQuestions
operation.
SERVICE_ANNOUNCEMENTS
This Service
supports the getServiceAnnouncements and
markAnnouncementsAsRead
operations.
PDTB2_KEY_PROVISION
This Service
supports the getKeyExchangeObject
operation.
Parent(s): supportedOptionalOperations
The user's preferred language of communication with the Service.
Data type: xs:language
Parent(s): config
Allowed values:
PDTB2
This Reading System supports DAISY Protected Digital Talking Book 2.
Parent(s): supportedContentProtectionFormats
The identifier of a transfer protocol. Identifiers are as given in the protocol's specification.
Data type: xs:string
Parent(s): additionalTransferProtocols
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.
Data type: xs:boolean
Parent(s): config
Content model: empty element
Parent(s): resources
uriThe URI of the resource.
Use: required
Data type: xs:anyURI
mimeTypeThe [MIME] type of the resource.
Use: required
Data type: xs:string
sizeThe size of the resource in bytes.
Use: required
Data type: xs:long
localURIThe local relative path of the resource.
The value of this attribute is a URI relative to the Content's root directory.
Use: required
Data type: xs:anyURI
lastModifiedDateThe last modified time of the resource.
Use: optional
Data type: xs:dateTime
A sample of the Content that the User may retrieve without the Content being issued.
Content model: empty element
Parent(s): contentMetadata
idThe Content Identifier of the sample.
Reading Systems may retrieve the sample's resource list by calling
getContentResources with this
identifier as the parameter. Reading Systems must not invoke
issueContent using the identifier 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
The identity of the Service.
Content model: ( label? )
Parent(s): serviceAttributes
idThe identifier of the Service.
This specification does not require a specific scheme to be used for this identifier. The identifier should not change while the Service remains active, and it should be universally unique.
A recommended expression form is a hyphen-separated
string consisting of a country code 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-onlineLibrary.
Use: required
Data type: xs:NMTOKEN
The identity of the Service Provider.
Content model: ( label? )
Parent(s): serviceAttributes
idThe identifier of the Service Provider.
This specification does not require a specific scheme to be used for this identifier. The identifier should not change while the Service provider remains active, and it should be universally unique.
A recommended expression form is a hyphen-separated
string consisting of a country code from
[ISO 3166], followed by an agency
code unique within its country. For example,
us-afb.
Use: required
Data type: xs:NMTOKEN
The total size of the resources making up the Content, in bytes.
Data type: xs:long
Parent(s): metadata
Specifies which Content formats the Reading System supports. A Service may use this information to choose which formats to offer to the Reading System as Content. This specification does not specify the behavior of the Service if this list is empty.
Content model: ( contentFormat* )
Parent(s): config
Specifies which Content protection (Digital Rights Management) standards the Reading System supports, if any.
Content model: ( protectionFormat* )
Parent(s): config
A list of Content Selection Methods supported by this Service. A Service must support at least one of the two methods.
Content model: ( method{1, 2} )
Parent(s): serviceAttributes
The means of User input to the Service that the Reading System supports.
If the Reading System does not support any means of input, the inputTypes element must be empty.
Content model: ( input* )
Parent(s): config
Specifies which [MIME] types the Reading System supports.
This applies to both Content and Service messages (labels).
A Service may use this information to choose which resource 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. This specification does not specify the behavior of the Service if both this and the supportedContentFormats lists are empty.
Content model: ( mimeType* )
Parent(s): config
Specifies which (if any) of the optional operations are supported by the Service.
Content model: ( operation* )
Parent(s): serviceAttributes
A list of the audio codecs (if any) supported in userResponses in addition to [RIFF WAVE].
Content model: ( codec* )
Parent(s): serviceAttributes
Specifies whether this Service supports the inclusion of audio in labels.
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.
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.
Data type: xs:boolean
Parent(s): config
Specifies whether getQuestions
with the reserved parameter search is
supported by the Service.
Data type: xs:boolean
Parent(s): serviceAttributes
Specifies whether getQuestions
with the reserved parameter back is
supported by the Service.
Data type: xs:boolean
Parent(s): serviceAttributes
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.
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).
Content model: ( data? )
Parent(s): userResponses
questionIDThe identifier of the question being answered.
The following three values of this attribute are reserved for use as defined below:
default
The root question (main menu) from the Service. (This value is used to initiate a dynamic menu operation sequence, and does not reflect an answered question.)
A Service that supports Dynamic Menus must support this reserved identifier.
search
The Service's search menu.
A Service is not required to support the
search reserved identifier. A
Service must explicitly declare whether it supports
this identifier in serviceAttributes.
back
The previous question from the Service during a dynamic menu operation sequence.
A Service is not required to support the
back reserved identifier. A Service must
explicitly declare whether it supports this identifier in
serviceAttributes.
Use: required
Data type: xs:NMTOKEN
valueIn 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
The version 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.
[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 1] XML Schema Part 1: Structures Second Edition . 28 October 2004.
[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.
The Service Provider must publish a WSDL document
at some URI. The WSDL document must import
http://www.daisy.org/projects/daisy-online-delivery/do-wsdl-10.wsdl into the namespace
http://www.daisy.org/ns/daisy-online/.
It must define a service with one port
bound to DaisyOnlineService in the http://www.daisy.org/ns/daisy-online/ namespace.
Example A.1. An example published WSDL document
<?xml version="1.0" encoding="utf-8"?>
<definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://www.daisy.org/ns/daisy-online/"
xmlns="http://schemas.xmlsoap.org/wsdl/"
targetNamespace="http://www.daisy.org/ns/daisy-online/">
<import namespace="http://www.daisy.org/ns/daisy-online/"
location="http://www.daisy.org/projects/daisy-online-delivery/do-wsdl-10.wsdl"/>
<service name="example">
<documentation>
Example DAISY Online Service
</documentation>
<port name="examplePort" binding="tns:DaisyOnlineService">
<soap:address location="http://example.org/daisy-online/"/>
</port>
</service>
</definitions>
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:
Johan Abbors, PratSam
Hiro Fujimori, Plextor
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
Matt Garrish, CNIB
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