Skip to content

Commit

Permalink
introduce starttime and endtime
Browse files Browse the repository at this point in the history
  • Loading branch information
@nichtich
nichtich committed Jul 11, 2014
1 parent a31350e commit 0425f2a
Showing 1 changed file with 90 additions and 51 deletions.
141 changes: 90 additions & 51 deletions paia.md
View file
Expand Up @@ -327,7 +327,7 @@ For instance the following response could result from a request with malformed U
~~~~


## Data types
## Simple data types

The following data types are used to define request and response format:

Expand All @@ -340,13 +340,26 @@ boolean
default but unknown!
date
: A date value in `YYYY-MM-DD` format.
datetime
: A date value with mandatory timezone and optional time. The format is
`YYYY-MM-DD`, optionally followed by `hh:mm:ss`, mandatorily followed by
either `Z` for UTC or `+hh:mm` or `-hh:mm` for another timezone, where:

* YYYY indicates a year
* MM indicates a month
* DD indicates a day
* hh indicates an hour
* mm indicates a minute
* ss indicates a second

money
: A monetary value with currency (format `[0-9]+\.[0-9][0-9] [A-Z][A-Z][A-Z]`),
for instance `0.80 USD`.
email
: A syntactically correct email address.
URI
: A syntactically correct URI.

account state
: A nonnegative integer representing the current state of a patron account.
Possible values are:
Expand All @@ -359,6 +372,7 @@ account state

A PAIA server MAY define additional states which can be mapped to `1` by PAIA
clients. In JSON account states MUST be encoded as numbers instead of strings.

service status
: A nonnegative integer representing the current status in fulfillment of a
service. In most cases the service is related to a document, so the service
Expand All @@ -367,60 +381,78 @@ service status

0. no relation (this applies to most combinations of document and patron, and
it can be expected if no other state is given)
1. reserved (the document is not accessible for the user yet, but it will be)
2. ordered (the document is being made accessible for the user)
1. reserved (the document is not accessible for the patron yet, but it will be)
2. ordered (the document is being made accessible for the patron)
3. held (the document is on loan by the patron)
4. provided (the document is ready to be used by the patron)
5. rejected

A PAIA server MUST NOT define any other service status. In JSON service status
MUST be encoded as numbers instead of strings.

document
: A key-value structure with the following fields

name occ data type description
----------- ------ --------------------- ----------------------------------------------------------
status 1..1 service status status (0, 1, 2, 3, 4, or 5)
item 0..1 URI URI of a particular copy
edition 0..1 URI URI of a the document (no particular copy)
requested 0..1 URI URI that was originally requested
about 0..1 string textual description of the document
label 0..1 string call number, shelf mark or similar item label
queue 0..1 nonnegative integer number of waiting requests for the document or item
renewals 0..1 nonnegative integer number of times the document has been renewed
reminder 0..1 nonnegative integer number of times the patron has been reminded
duedate 0..1 date date of expiry of the service status (most times loan)
cancancel 0..1 boolean whether an ordered or provided document can be canceled
canrenew 0..1 boolean whether a document can be renewed
error 0..1 string error message, for instance if a request was rejected
storage 0..1 string location of the document
storageid 0..1 URI location URI
----------- ------ --------------------- ----------------------------------------------------------


For each document at least an item URI or an edition URI MUST be given.
Together, item and edition URI MUST uniquely identify a document within
the set of documents related to a patron.

The response fields `label`, `storage`, `storageid`, and `queue`
correspond to properties in DAIA.

An example of a document (with status 5=rejected) serialized in JSON is
given below. In this case an arbitrary copy of a selected document was
requested and mapped to a particular copy that turned out to be not accessible:
## Document data type

A **document** is a key-value structure with the following fields

name occ data type description
----------- ------ --------------------- ----------------------------------------------------------
status 1..1 service status status (0, 1, 2, 3, 4, or 5)
item 0..1 URI URI of a particular copy
edition 0..1 URI URI of a the document (no particular copy)
requested 0..1 URI URI that was originally requested
about 0..1 string textual description of the document
label 0..1 string call number, shelf mark or similar item label
queue 0..1 nonnegative integer number of waiting requests for the document or item
renewals 0..1 nonnegative integer number of times the document has been renewed
reminder 0..1 nonnegative integer number of times the patron has been reminded
starttime 0..1 datetime date and time when the status began
endtime 0..1 datetime date and time when the status will expire
duedate 0..1 date date when the current status will expire (*deprecated*)
cancancel 0..1 boolean whether an ordered or provided document can be canceled
canrenew 0..1 boolean whether a document can be renewed
error 0..1 string error message, for instance if a request was rejected
storage 0..1 string location of the document
storageid 0..1 URI location URI
----------- ------ --------------------- ----------------------------------------------------------


For each document at least an item URI or an edition URI MUST be given.
Together, item and edition URI MUST uniquely identify a document within
the set of documents related to a patron.

The fields `starttime` and `endtime` MUST be interpreted as following:

status starttime endtime
-------- -------------------------------- --------------------------------------------------------
0 - -
1 when the document was reserved when the reserved document is expected to be available
2 when the document was ordered when the ordered document is expected to be available
3 when the document was lend when the loan period ends or ended (due)
4 when the document is provided when the provision will expire
5 when the request was rejected -

Note that timezone information is mandatory in these fields. The field
`duedate` is deprecated. Clients SHOULD only use it as `endtime` if no
`endtime` was given.

The response fields `label`, `storage`, `storageid`, and `queue`
correspond to properties in DAIA.

An example of a document (with status 5=rejected) serialized in JSON is
given below. In this case an arbitrary copy of a selected document was
requested and mapped to a particular copy that turned out to be not accessible:

~~~~ {.json}
{
"status": 5,
"item": "http://example.org/items/barcode1234567",
"edition": "http://example.org/documents/9876543",
"requested": "http://example.org/documents/9876543",
"error": "sorry, we found out that our copy is lost!"
}
~~~~
~~~~ {.json}
{
"status": 5,
"item": "http://example.org/items/barcode1234567",
"edition": "http://example.org/documents/9876543",
"requested": "http://example.org/documents/9876543",
"error": "sorry, we found out that our copy is lost!"
}
~~~~

See [documents in RDF] for a mapping in RDF.
See [documents in RDF] for a mapping in RDF.

# PAIA core

Expand Down Expand Up @@ -912,11 +944,11 @@ paia:OutstandingFees a rdfs:Resource ;

[documents in RDF]: #documents-in-rdf

Lists of documents, as returned by the PAIA core methods [items], [request],
[renew], and [cancel], are represented as sets of events. Each event is an
instance of **[ssso:ServiceEvent]** from the [Simple Service Status Ontology]
(SSSO) and an instance of of a specific document service class defined in the
[Document Service Ontology] (DSO).
Lists of [documents](#document-data-type), as returned by the PAIA core methods
[items], [request], [renew], and [cancel], are represented as sets of events.
Each event is an instance of **[ssso:ServiceEvent]** from the [Simple Service
Status Ontology] (SSSO) and an instance of of a specific document service class
defined in the [Document Service Ontology] (DSO).

The current [service status](#data-types) of a document service event is given
by an instance-relationship (rdf:type) with one of the following classes:
Expand Down Expand Up @@ -956,6 +988,13 @@ The service event is connected to a patron as [service:ServiceConsumer]
(with property [service:consumedBy]) and to a document
(*with a property yet to be defined*).

The `starttime` end `endtime` can be mapped to any of the following properties,
among others:

starttime
: schema:startDate, prov:prov:startedAtTime, prov:qualifiedStart
endtime
: schema:endDate, prov:endedAtTime, prov:qualifiedEnd

[ssso:ServiceEvent]: http://purl.org/ontology/ssso#ServiceEvent
[dso:Loan]: http://purl.org/ontology/dso#Loan
Expand Down

0 comments on commit 0425f2a

Please sign in to comment.