his document specifies the outdated specification of DAIA 0.5. The current specification (DAIA 1.0) is available at <http://purl.org/NET/DAIA>

Authors: Jakob Voss (VZG) <jakob.voss@gbv.de>, Uwe Reh (Hebis) <reh@hebis.uni-frankfurt.de>

Abstract

The Document Availability Information API (DAIA) defines a data model with serializations in JSON and XML to encode information about the current availability of documents. This document defines the serialization formats DAIA/JSON and DAIA/XML and a HTTP query API to query DAIA information.

This document is publically available under the terms of the Creative-Commons Attribution-No Derivative (CC-ND 3.0) license.

1. Introduction

Core components of the DAIA data model

The Document Availability Information API (DAIA) defines a response format that encodes information about the current availability of documents. The general structure of a DAIA response is a tree of nested elements. A description of the data model is outlined at one page: http://ws.gbv.de/daia/daiamodel.pdf

DAIA format structures can be encoded either in JSON (DAIA/JSON) or in XML (DAIA/XML). The current XML Schema is located at http://purl.org/NET/DAIA/schema.xsd. The XML namespace and URI for DAIA/XML is http://ws.gbv.de/daia/. The version attribute contains the current version of the schema (0.5).

2. Structure and Encoding

In the following paragraphs we want to give a short introduction to DAIA format. Examples of equivalent DAIA document 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.

 DAIA/JSONDAIA/XML
repeated
"item": [ { ... }, { ... }, ... ]
<item ... > ... </item>
<item ... > ... </item>
...
not repeated
"item": [ { ... } ]
<item ... > ... </item>

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:

For examples in DAIA/RDF the following namespace prefixes are used:

2.1. Root element

Each full DAIA document contains exactly one root element. In DAIA/XML the root element name is daia, in DAIA/JSON the root element is just an unnamed object. The attributes and child elements are as follows:

In DAIA/XML you must further specifiy the XML namespace http://ws.gbv.de/daia/ and may refer to the DAIA XML Schema http://ws.gbv.de/daia/daia.xsd as shown in the following example. In DAIA/JSON you can include a fixed child element that points to the DAIA specification and namespace:

Example:

DAIA/JSONDAIA/XML
{
  "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>

2.2. Document element

The document element describes a single document. Nevertheless, several instances of a documents (e.g. copies of a book) can exist. For the instances, have a look at the item element below.

In DAIA/XML messages and items can be mixed in any order.

Example:

DAIA/JSON
"document" : [ {
  "href" : "https://kataloge.uni-hamburg.de/DB=1/PPNSET?PPN=57793371X",
  "id" : "gvk:ppn:57793371X",
  "item" : [ {  }, {  }, {  } ]
} ]
DAIA/XML
<document href="https://kataloge.uni-hamburg.de/DB=1/PPNSET?PPN=57793371X" 
          id="gvk:ppn:57793371X">
  <item/>
  <item/>
  <item/>
</document>
DAIA/RDF (Turtle syntax)
<gvk:ppn:57793371X> a bibo:Document ;
  foaf:primaryTopicOf <https://kataloge.uni-hamburg.de/DB=1/PPNSET?PPN=57793371X> ;
  daia:exemplar [ ], [ ], [ ] .

2.3. Item element

The item node references a single instance (copy, URI, etc.) of a document. The availability information is of course connected to the item nodes.

Multiple service status can be given for an item represented by different available/unavailable elements.

Example:

DAIA/JSONDAIA/XMLDAIA/RDF (Turtle syntax)
"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>
<id:123> a frbr:Item ;
  dct:description "foo"@en ; 
  daia:label "bar" ;
  daia:heldBy <id:abc> ;
  daia:availableFor [ a daia:Service/Presentation ] ;
  daia:availableFor [ a daia:Service/Loan ] ;
  daia:availableFor [ a daia:Service/Interloan ] ;
  daia:unavailableFor [ a daia:Service/Openaccess ] ;
<id:abc> a foaf:Organization ; dcterms:isPartOf [
  a foaf:Organization ; dcterms:hasPart <id:abc> ] .

In DAIA/RDF, an Item element corresponds to an instance of frbr:Item. Partial items refer to items which contain less (narrower) or more (broader) than the whole document:

 

narrower in DAIA/XML
<document id="x:123">
  <item id="x:ABC" part="narrower"/>
</document>
narrower in DAIA/RDF
<x:123> a bibo:Document ; daia:narrowerExemplar <x:ABC> .
<x:123> a bibo:Document ; dcterms:hasPart [ daia:exemplar <x:ABC> ] } .
broader in DAIA/XML
<document id="x:123">
  <item id="x:ABC" part="broader"/>
</document>
broader in DAIA/RDF
<x:123> a bibo:Document ; daia:broaderExemplar <x:ABC> .
<x:123> a bibo:Document ; daia:exemplar [ dcterms:hasPart <x:ABC> ] } .

2.4. Available element

The structure of an available element is:

In DAIA/XML messages and limitations can be mixed in any order.

Services defined in DAIA

ServiceURI*Definition
presentationhttp://purl.org/ontology/daia/Service/PresentationThe item is accessible within the institution (in their rooms, in their intranet etc.)
loanhttp://purl.org/ontology/daia/Service/LoanThe item is accessible outside of the institution (by lending or online access) for a limited time
openaccesshttp://purl.org/ontology/daia/Service/OpenaccessThe item is accessible freely without any restrictions by the institution (Open Access or free copies)
interloanhttp://purl.org/ontology/daia/Service/InterloanThe item is accessible mediated by another institution.
unspecified*http://purl.org/ontology/daia/ServiceThe item is accessible for an unspecified purpose by an unspecified way

It is recommended to mainly support the four specified services in non-URI form instead of using custom service URIs. If you define a new service URI you should document it as detailed as possible and discuss with other DAIA implementers to ensure interoperability. In terms of RDF all custom services must be subclasses of http://purl.org/ontology/daia/Service so a client can treat an unknown service as instance of an unspecified DAIA service. 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).


Example

DAIA/JSONDAIA/XMLDAIA/RDF (experimental)
"available": [ {
  "service":"loan",
  "delay":"PT2H"
] }
<available service="loan" delay="PT2H" />
[ ] daia:availableFor [
  a daia:Service/Loan ;
  daia:delay "PT2H"^^xsd:duration 
] .

2.5. Unavailable element

The structure of an unavailable element is identical to the structure of the available element in most cases.

If no expected element is given, it is not sure whether the item will ever be available, so this is not the same as setting it to unknown. If no queue element is given, it may (but does not need to) be assumed as zero. In DAIA/XML messages and limitations can be mixed in any order.

Example:

DAIA/JSONDAIA/XML
"unavailable": [ {
  "service":"presentation",
  "delay":"PT4H"
} ]
<unavailable service="presentation" delay="PT4H" />

2.6. Messages

Messages can occur at several places in a DAIA response. The structure of a message element is:

Notes:

Example:

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:

DAIA/JSONDAIA/XML
"message" : [ {
  "content":"request failed",
  "lang":"en"
} ]
<message lang="en">request failed</message>

2.7. Additional entities

In this section, the additional entries institution, department, storage and limitation are discussed.

The data structure of all these nodes is identical and discussed below.

Data structure

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.

Examples:

DAIA/JSON
"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" }
DAIA/XML
<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>

3. DAIA/RDF

All DAIA documents, given in DAIA/JSON or DAIA/XML can also be expressed in RDF. The DAIA ontology used for this purpose is called DAIA/RDF. The ontology is located at http://purl.org/ontology/daia/.

4. Query API

DAIA Query API

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.

Examples:

Base URLDocument URIsFormatQuery URL
http://example.com/gvk:ppn:588923168DAIA/XMLhttp://example.com/?id=gvk:ppn:588923168&format=xml
http://example.com/?cmd=daiagvk:ppn:588923168DAIA/JSONhttp://example.com/?cmd=daia&id=gvk:ppn:588923168&format=json
http://example.com/gvk:ppn:588923168 and gvk:ppn:365058963DAIA/JSONhttp://example.com/?id=gvk:ppn:588923168%7Cgvk:ppn:365058963&format=json

DAIA Storage API

The DAIA-Storage-API is an additional API, similar to the DAIA-API, but to retrieve Storage information only. The request parameter are also format and id but the latter can be any Unicode character string (it is up to the specific implementation of an DAIA-Storage-API what kinds of identifiers to expect). Typical applications include mapping from call number to locations. The request is limited to any combination of the elements institution, department, storage, and message. A DAIA Storage API and a DAIA API must not share the same base URL.

5. References

6. Notes (Informative)

6.1 Integrity rules

If department and institution have same id, the department SHOULD be ignored.