Versions Compared

Old Version 2

changes.mady.by.user James English

Saved on

compared with

New Version Current

changes.mady.by.user James English

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

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

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 is available, then opds:since is the time at which the resource became available, and opds: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 and opds:until is the expiration date.

  • If opds:state is unavailable, then opds:since is the last time at which the resource was available (probably not useful) and opds:until is the estimated time at which the resource will become available. The opds:until time may be conditional on the user taking some immediate action, such as putting a hold on the resource.

  • If opds:state is reserved, then opds:since is the time at which the authenticated user placed their hold, and opds:until is the estimated time at which the resource will become available (probably by moving into the ready 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 an unavailable resource may indicate the estimated time at which the resource will become available if the patron joins the hold queue now,

  • If opds:state is ready, then opds:since is the time at which the resource became ready to the authenticated user, and opds:until is the time at which the resource will revert to its default availability (probably unavailable).

Anchor
copies
copies

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

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
Fullfilment
Fullfilment

Fulfillment states

With the combination fo opds:state and acquisition relations, a book can generally fall in to one of 6 states:

  1. Open Access: The book can be downloaded immediately via open-access links without any loan or auth requirements.
  2. Available to borrow: There is no queue and the book can be borrowed immediately by a patron.
  3. Available to reserve: The book cannot be borrowed right now, but the patron can join the queue to borrow it.
  4. Reserved: The patron is currently in the queue to borrow.
    • Condition: opds:state is reserved.
  5. 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.
  6. Available to access: The patron may access the book (download, read in app, etc) either directly or indirectly immediately.

Anchor
examples
examples

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).

...