...
This specification documents OPDS extensions that allow public libraries to communicate these scenarios of artificial scarcity -- availability, holds queues, loan duration -- to OPDS clients. It also sets out guidelines for how an OPDS client should process the standard http://opds-spec.org/acquisition/borrow
link relation.
Extensions
Anchor availability availability
opds:availability
OPDS operates on the background assumption that a book with an OPDS entry is available right now and will always be available. In a public library environment, this is generally not true:
...
The opds:availability
element is OPTIONAL. If it's not present, an OPDS client MUST assume that the resource at the other end of the atom:link
is currently available.
Anchor state state
Anchor | ||||
---|---|---|---|---|
|
opds:state
...
Answers the question "Can I have this book?
...
" The opds:state
attribute is REQUIRED for an opds:availability
element.
...
available
: The resource is available right now. If the user is authenticated, this means the resource is available to that user -- it might not be available generally. If the user is not authenticated, this means that any authenticated user can expect to be able to obtain the resource.This is not a binding promise. When the user follows the link, the resource may turn out not to be available after all.
unavailable
: The resource is not currently available. The user can still follow the acquisition link, but this will result in some intermediate step, such as a preorder or a hold, rather than the immediate acquisition of the resource.This is not a binding promise. When the user follows the link, the resource may turn out to be available after all.
reserved
: The authenticated user will get the resource eventually, but it's not available now. This generally means the authenticated user has placed a hold on the resource and is waiting in a holds queue.ready
: The resource is ready for the authenticated user, but not for the general public. The user can acquire the resource now, but if they don't act soon, they will lose the opportunity.This is not a binding promise. When the user follows the link, it may turn out that the reservation has expired and the resource is now unavailable.
Anchor since and until since and until
Anchor | ||||
---|---|---|---|---|
|
opds:since
and opds:until
-
Answers the questions "When does my loan expire?
...
" The date attributes are OPTIONAL in an opds:status
element. They are used to help the patron plan for the future.
If
opds:state
isavailable
, thenopds:since
is the time at which the resource became available, andopds:until
is the time at which the resource will no longer be available.For example, if the patron has a resource on loan,
opds:since
is the loan's start date andopds:until
is the expiration date.If
opds:state
isunavailable
, thenopds:since
is the last time at which the resource was available (probably not useful) andopds:until
is the estimated time at which the resource will become available. Theopds:until
time may be conditional on the user taking some immediate action, such as putting a hold on the resource.If
opds:state
isreserved
, thenopds:since
is the time at which the authenticated user placed their hold, andopds:until
is the estimated time at which the resource will become available (probably by moving into theready
state). This estimate can't be exact because it depends on the behavior of people further up in the hold queue.If the patron does not have an active loan, then
opds:until
for anunavailable
resource may indicate the estimated time at which the resource will become available if the patron joins the hold queue now,If
opds:state
isready
, thenopds:since
is the time at which the resource became ready to the authenticated user, andopds:until
is the time at which the resource will revert to its default availability (probablyunavailable
).
Anchor copies copies
Anchor | ||||
---|---|---|---|---|
|
opds:copies
...
Answers the question "How many copies does the library have?
...
" The opds:copies
element describes the number of licenses the server owns for a resource. Although this is intended to describe electronic licenses for virtual resources, it may also be used to represent physical books in a bookstore or branch library.
...
If the opds:state
is unavailable
, then opds:available
SHOULD be 0
.
Anchor holds holds
Anchor | ||||
---|---|---|---|---|
|
opds:holds
-
Answers question "Where am I in line?
...
" The opds:holds
element describes the people waiting in line for access to a resource.
...
If the opds:state
is available
, then opds:total
SHOULD be 0
.
...
Anchor | ||||
---|---|---|---|---|
|
Fulfillment states
With the combination fo opds:state
and acquisition relations, a book can generally fall in to one of 6 states:
- Open Access: The book can be downloaded immediately via open-access links without any loan or auth requirements.
- Condition: Presence of link(s) with
http://opds-spec.org/acquisition/open-access
rel.
- Condition: Presence of link(s) with
- Available to borrow: There is no queue and the book can be borrowed immediately by a patron.
- Condition:
opds:state
isavailable
andhttp://opds-spec.org/acquisition/borrow
link is present.
- Condition:
- Available to reserve: The book cannot be borrowed right now, but the patron can join the queue to borrow it.
- Condition:
opds:state
isunavailable
andhttp://opds-spec.org/acquisition/borrow
is present.
- Condition:
- Reserved: The patron is currently in the queue to borrow.
- Condition:
opds:state
isreserved
.
- Condition:
- Ready to borrow: The patron has waited through the queue and now has a hold on the book. They must borrow it before their hold expires, or they lose their spot in line.
- Condition:
opds:state
isready
andhttp://opds-spec.org/acquisition/borrow
is present.
- Condition:
- Available to access: The patron may access the book (download, read in app, etc) either directly or indirectly immediately.
- Condition:
opds:state
isavailable
and link(s) withhttp://opds-spec.org/acquisition
rel are present.
- Condition:
Anchor | ||||
---|---|---|---|---|
|
Examples
This example shows a book which is not currently available, but which can be put on hold (the first link, with the relation http://opds-spec.org/acquisition/borrow
) or pre-ordered (the second link, with the relation http://opds-spec.org/acquisition/buy
).
...