The Document Availability Information API (DAIA) defines model of document availability, a set of exchangeable serializations of this model (in JSON and XML), and an HTTP API to query document availability information encoded in any of these serializations. The DAIA data model basically consists of abstract documents, concrete holdings of documents, and document services, with an availability status.
Information expressed by DAIA can also be encoded in RDF as described with the DAIA Ontology
This document is a draft of what is going to be DAIA 1.0 specification. Version 0.5 is available at https://www.gbv.de/wikis/cls/DAIA_-_Document_Availability_Information_API.
All documentation and schemas are generated from the source file daia.md
written in Pandoc’s Markdown and converted with makespec.
Updates and sources of DAIA 1.0 can be found at http://github.com/gbv/daiaspec/. The current version of this document was last modified at 2015-04-22 with revision b1605dd.
This document is publically available under the terms of the Creative-Commons Attribution-ShareAlike Derivative (CC-BY-SA 3.0) license. Feedback is welcome:
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
DAIA serializations in XML (DAIA/XML) is formally described by an XML schema. The DAIA/XML Schema is identified by the XML namespace http://ws.gbv.de/daia/
. The XML namespace prefix daia
is recommeded..
The current XML Schema is located at http://purl.org/NET/DAIA/schema.xsd.
In the following paragraphs we want to give a short introduction to DAIA format. Examples of equivalent DAIA response fragments are given in DAIA/JSON and DAIA/XML. The basic information entities of DAIA format are:
Daia entities in DAIA/JSON are encoded as simple nodes with child nodes, daia entities in DAIA/XML are encoded as XML-elements with attributes and child-elements. XML elements include namespaces so you must use an XML parser with support of namespaces to process DAIA/XML. Below the possible and mandatory attributes and child elements or nodes of each daia entities are defined. If an entity is marked with a question mark (?
) it is optional. If an entity is marked with a star (\*
) it is repeatable and optional. All other entities are mandatory and non-repeatable. Repeatable elements in DAIA/XML are just line up after another. Repeatable elements in DAIA/JSON must be encoded as array with one ore more content elements.
The order or repeatable elements (message, limitation, document, item, available, unavailable) is irrelevant. DAIA servers and clients MAY sort these lists as they like.
DAIA/JSON | DAIA/XML | |
---|---|---|
repeated |
|
|
not repeated |
|
|
Content of entities that must not have child nodes are encoded as Unicode strings, numbers, or boolean values. Unless a more specific limitation is defined with an XML Schema Datatype, the content must be an Unicode string (but it may be the empty string). DAIA uses the following XML Schema Datatypes:
xsd:boolean
- in DAIA/XML one of true
, false
, 1
, 0
. In DAIA/JSON one of true
, false
(but literally instead of string).xsd:language
- must conform to the pattern [a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})\*
.xsd:date
- must follow the form \d{4}[-](\d\d)[-](\d\d)((([+-])\d\d:\d\d)|Z)?
.xsd:dateTime
- must follow the form \d{4}[-](\d\d)[-](\d\d)[T](\d\d)[:](\d\d)[:]\d\d([.]\d+)?((([+-])\d\d:\d\d)|Z)?
.xsd:duration
- must follow the form -PnYnMnDTnHnMnS
. Empty parts can be omitted.xsd:integer
- must conform to the pattern [+-]?[0-9]+
in DAIA/XML. In DAIA/JSON it is an integer.xsd:nonNegativeInteger
- must conform to the pattern ([+]?[0-9]+|-0)
in DAIA/XML. In DAIA/JSON it is a non-negative integer.xsd:anyURI
- must conform to the pattern of an URI.A DAIA response in DAIA/XML and DAIA/JSON contains exactely one root element.
In DAIA/XML the root element name is daia. The XML namespace http://ws.gbv.de/daia/
MUST be specified and the XML Schema http://ws.gbv.de/daia/daia.xsd
MAY be referred to. In DAIA/JSON, the fixed child element schema with value http://ws.gbv.de/daia/
MAY be used to refer to DAIA specification and namespace.
0.5
)xsd:dateTime
.{
"version" : "0.5",
"schema" : "http://ws.gbv.de/daia/",
"timestamp" : "2009-06-09T15:39:52.831+02:00",
"institution" : { }
}
<daia xmlns="http://ws.gbv.de/daia/" version="0.5"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://ws.gbv.de/daia/ http://ws.gbv.de/daia/daia.xsd"
timestamp="2009-06-09T15:39:52.831+02:00">
<institution/>
</daia>
Equivalent DAIA/XML with different namespace prefix:
<d:daia xmlns:d="http://ws.gbv.de/daia/" version="0.5"
xmlns:s="http://www.w3.org/2001/XMLSchema-instance"
s:schemaLocation="http://ws.gbv.de/daia/ http://ws.gbv.de/daia/daia.xsd"
timestamp="2009-06-09T15:39:52.831+02:00">
<d:institution/>
</d:daia>
The document element describes a single document. Nevertheless, several instances of a document (e.g. copies of a book) can exist. For these instances, have a look at the item element below.
xsd:anyURI
.xsd:anyURI
.{
"document" : [ {
"href" : "https://kataloge.uni-hamburg.de/DB=1/PPNSET?PPN=57793371X",
"id" : "gvk:ppn:57793371X",
"item" : [ { }, { }, { } ]
} ]
}
<document href="https://kataloge.uni-hamburg.de/DB=1/PPNSET?PPN=57793371X"
id="gvk:ppn:57793371X">
<item/>
<item/>
<item/>
</document>
The item
node references a single instance (copy, URI, etc.) of a document. The availability information is of course connected to the item nodes.
xsd:anyURI
.xsd:anyURI
.part="narrower"
) or contains more than the document (part="broader"
)Multiple service status can be given for an item represented by different available/unavailable elements.
{
"item" : [ {
"id" : "id:123",
"message" : [ { "lang": "en", "content": "foo" } ],
"department" : { "id": "id:abc" },
"label" : "bar",
"available" : [ {"service" : "presentation"},
{"service" : "loan"},
{"service" : "interloan"} ],
"unavailable" : [ {"service" : "openaccess"} ]
} ]
}
<item id="id:123">
<message lang="en">foo</message>
<department id="id:abc" />
<label>bar<label>
<available service="presentation" />
<available service="loan" />
<available service="interloan" />
<unavailable service="openaccess" />
</item>
Partial items refer to items which contain less (narrower
) or more (broader
) than the whole document:
narrower in DAIA/XML |
|
narrower in DAIA/RDF |
|
broader in DAIA/XML |
|
broader in DAIA/RDF |
|
xsd:anyURI
.xsd:anyURI
.unknown
or an ISO time period. If missing, then there is probably no significant delay. Type xsd:duration
or the string unknown
.Typical DSO Services used in DAIA
presentation
: http://purl.org/ontology/dso#Presentation The item is accessible within the institution (in their rooms, in their intranet etc.).
loan
: http://purl.org/ontology/dso#Loan
The item is accessible outside of the institution (by lending or online access) for a limited time.
openaccess
: http://purl.org/ontology/dso#Openaccess
The item is accessible freely without any restrictions by the institution (Open Access or free copies).
interloan
: http://purl.org/ontology/dso#Interloan
The item is accessible mediated by another institution.
unspecified : http://purl.org/ontology/dso#DocumentService
The item is accessible for an unspecified purpose by an unspecified way.
One MAY use custom service types, not specified in DSO, if these services are specified with an URI as subclasses of [dso:DocumentService].
If you omit the service element then the unspecified service must be assumed (do not use the string unspecified
or the empty string but just omit to specify a service).
{
"available": [ { "service":"loan", "delay":"PT2H"
}
<available service="loan" delay="PT2H" />
Messages can occur at several places in a DAIA response. Messages are not meant to be shown to end-users, but only used for debugging. If you need a DAIA message to transport some relevant information, you likely try to use DAIA for the wrong purpose.
xsd:language
.content
is an empty string, the content element/attribute SHOULD be omitted.xsd:integer
.In DAIA/XML the message
element is a repeatable XML element with optional attributes lang
and errno
and the string encoded as element content. In DAIA/JSON a message
element is an object with lang
, errno
, and string
as keys. Multiple messages are combined in a JSON array:
{
"message" : [ {
"content":"request failed",
"lang":"en"
} ]
}
<message lang="en">request failed</message>
In this section, the additional entries institution, department, storage and limitation are discussed.
institution nodes refer to an institution (e.g., the University of Hamburg), referenced by an ISIL, a hyperlink and/or a name.
department nodes refer to a single department of an institution, e.g., the Faculty of Computer Science of Bielefeld University. They should be used when the institution has an own library.
storage nodes deliver information about the place where an item is stored (“2nd floor”). i
limitation nodes give information of limitations of the availability of an item
The content of these nodes is identical and discussed below.
xsd:anyURI
.xsd:anyURI
.If content
is an empty string, it should be removed in DAIA encodings. Applications may treat a missing content
as the empty string. It is recommended to supply an id
property to point to a taxonomy or authority record and a href
property to provide a hyperlink to information about the specified entity.
TODO: multilingual content
{
"institution" : { "href" : "http://www.tib.uni-hannover.de/" }
...
"department" : {
"id" : "info:isil/DE-7-022",
"content" : "Library of the Geographical Institute, Goettingen University"
}
...
"limitation" : { "content" : "3 day loan" }
}
<institution href="http://www.tib.uni-hannover.de/"/>
...
<department id="info:isil/DE-7-022">Library of the Geographical Institute, Goettingen University</department>
...
<limitation>3 day loan</limitation>
A DAIA-API is provided in form of a Base URL that can be queried by HTTP (or HTTPS) GET. The Base URL may contain fixed query parameters but it must not contain the query parameters id
and format
. A DAIA query is constructed of the Base URL and a query parameter id
for the document URI to be queried for and format
with one of xml
and json
. The value of the format
parameter is case insensitive. The response muste be a DAIA/XML document for format=xml
and a DAIA/JSON document for format=json
. If no format
parameter is given or if the parameter value is no known value, a DAIA/XML document may be returned, but you can also return other formats. In particular a DAIA-API may return DAIA/RDF in RDF/XML for format=rdfxml
and DAIA/RDF in Turtle for format=ttl
. The HTTP response code must be 200 for all non-empty responses (DAIA/JSON and DAIA/XML) and 404 for empty responses (for instance RDF/XML in Turtle format). Multiple document URIs can be provided by concatenating them with the vertical bar (|
, %7C
in URL-Encoding) but a DAIA server may limit queries to any positive number of URIs.
A DAIA server SHOULD include the HTTP response header Content-Language
to indicate the language of textual response fields. The HTTP request header Accept-Language
SHOULD be respected to select between multiple languages.
Examples:
Base URL | Document URIs | Format | Query URL |
---|---|---|---|
http://example.com/ |
gvk:ppn:588923168 |
DAIA/XML | http://example.com/?id=gvk:ppn:588923168&format=xml |
http://example.com/?cmd=daia |
gvk:ppn:588923168 |
DAIA/JSON | http://example.com/?cmd=daia&id=gvk:ppn:588923168&format=json |
http://example.com/ |
gvk:ppn:588923168 and gvk:ppn:365058963 |
DAIA/JSON | http://example.com/?id=gvk:ppn:588923168%7Cgvk:ppn:365058963&format=json |
The following appendixes are informative only.
DAIA Simple is a boiled down version of a DAIA response consisting of plain key-value structure having the following fields:
openaccess
, loan
, presentation
, none
)
true
or false
)
true
. Allowed values must conform to xsd:duration
or the string unknown
.
false
. Allowed values must conform to xsd:date
or xsd:dateTime
or the string unknown
.
false
)
To give a few examples, encoded in JSON:
{ "service": "loan", "available": true }
{ "service": "loan", "available": false, "expected": "2014-12-07" }
{ "service": "presentation", "available": true }
{ "service": "openaccess", "available": true,
"href": "http://dx.doi.org/10.1901%2Fjaba.1974.7-497a" }
Note that DAIA Simple only covers one typical use case but it may not suitable for other applications.
The basic structure of DAIA is unlikely to change. However until DAIA 1.0 the following parts need to be finished:
The DAIA/XML namespace (currently http://ws.gbv.de/daia/) may be changed to a more stable PURL.
2015-04-22 15:39:46 +0200
: Use HTTP headers for languages (#4)2015-04-22 15:32:28 +0200
: moved DAIA ontology to independent document again2015-01-22 15:01:09 +0100
: redefined DAIA simple2014-06-30 16:39:52 +0200
: add link to http://purl.org/NET/DAIA2014-04-17 12:57:17 +0200
: forgot status=expected in DAIA Simple