The Document Availability Information API (DAIA) defines model of document availability, a set of exchangeable serializations of this model (in JSON, XML, and RDF), 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, each with an availability status.
This document is a draft of what is going to be DAIA 1.0 specification.
The previous version 0.5 is available at http://purl.org/NET/DAIA and DAIA ontology at http://uri.gbv.de/ontology/daia/.
The RDF ontology of DAIA/RDF is available in Turtle and in RDF/XML. Schema files for DAIA/XML will follow. 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 2013-07-08 12:41:28 +0200 with revision 3a6ffbe.
This document is publically available under the terms of the Creative-Commons Attribution-No Derivative (CC-ND 3.0) license. Feedback is welcome:
Revision history
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) and RDF (DAIA/RDF) are each formally described by a schema or ontology. The DAIA/XML Schema is identified by the XML namespace http://ws.gbv.de/daia/
. The DAIA/RDF Ontology is identified by the URI http://purl.org/ontology/daia/ which is also used URI namespace. The namespace prefix daia
is recommeded for both DAIA/XML and DAIA/RDF.
@prefix daia: <http://purl.org/ontology/daia/> .
@base <http://purl.org/ontology/daia/> .
The following namspace prefixes are used to refer to related ontologies:
@prefix bibo: <http://purl.org/ontology/bibo/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix dso: <http://purl.org/ontology/dso#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix org: <http://www.w3.org/ns/org#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix vann: <http://purl.org/vocab/vann/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
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 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/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:
xs:boolean
- in DAIA/XML one of true
, false
, 1
, 0
. In DAIA/JSON one of true
, false
(but literally instead of string).xs:language
- must conform to the pattern [a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})\*
.xs:date
- must follow the form \d{4}[-](\d\d)[-](\d\d)((([+-])\d\d:\d\d)|Z)?
.xs:dateTime
- must follow the form \d{4}[-](\d\d)[-](\d\d)[T](\d\d)[:](\d\d)[:]\d\d([.]\d+)?((([+-])\d\d:\d\d)|Z)?
.xs:duration
- must follow the form -PnYnMnDTnHnMnS
. Empty parts can be omitted.xs:integer
- must conform to the pattern [+-]?[0-9]+
in DAIA/XML. In DAIA/JSON it is an integer.xs:nonNegativeInteger
- must conform to the pattern ([+]?[0-9]+|-0)
in DAIA/XML. In DAIA/JSON it is a non-negative integer.xs:anyURI
- must conform to the pattern of an URI.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.
Properties
version
(attribute) - the daia version number (currently 0.5
)timestamp
(attribute) - the time the document was generated. Type xs:dateTime
.message
* (element) - (error) message(s) about the whole responseinstitution
? (element) - information about the institution that grants or knows about services and their availabilitydocument
* (element) - a group of items that can be refered to with one identifier. Please note that although the number of document elements can be zero or greater one, one single document entry should be considered as the default.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:
schema
(attribute) - DAIA namespace string http://ws.gbv.de/daia/
Example
DAIA/JSON
{
"version" : "0.5",
"schema" : "http://ws.gbv.de/daia/",
"timestamp" : "2009-06-09T15:39:52.831+02:00",
"institution" : { }
}
DAIA/XML
<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.
Properties
id
(attribute) - each document needs an unique id to query it (e.g. ISBN, ppn, etc.). Please consider that ids have to be URIs. Type xs:anyURI
.href
? (attribute) - a link to the document or to additional information. Type xs:anyURI
.message
* (element) - (error) message(s) about the document.item
* (element) - an instance or copy of the queried document (correspondends to the FRBR class of same name).In DAIA/XML messages and items can be mixed in any order.
Example in DAIA/JSON
{
"document" : [ {
"href" : "https://kataloge.uni-hamburg.de/DB=1/PPNSET?PPN=57793371X",
"id" : "gvk:ppn:57793371X",
"item" : [ { }, { }, { } ]
} ]
}
Example in DAIA/XML
<document href="https://kataloge.uni-hamburg.de/DB=1/PPNSET?PPN=57793371X"
id="gvk:ppn:57793371X">
<item/>
<item/>
<item/>
</document>
Example in DAIA/RDF
<gvk:ppn:57793371X> a bibo:Document ;
foaf:primaryTopicOf <https://kataloge.uni-hamburg.de/DB=1/PPNSET?PPN=57793371X> ;
daia:exemplar [ ], [ ], [ ] .
The item
node references a single instance (copy, URI, etc.) of a document. The availability information is of course connected to the item nodes.
Properties
id
? (attribute) - again, each item (instance) may have an unique ID (e.g., an individual call number for a book). Please consider that ids have to be URIs. Type xs:anyURI
.href
? (attribute) - a link to the item or to additional information. Type xs:anyURI
.part
? (attribute) - indicate that the item only contains a part of the document (part="narrower"
) or contains more than the document (part="broader"
)message
* (element) - (error) message(s) about the item.label
? (element) - a label that helps to identify and/or find the item (call number etc.)department
? (element) - an administrative sub-entitity of the institution that is responsible for this itemstorage
? (element) - a physical location of the item (stacks, floor etc.)available
* (element) - information about an available service with the item.unavailable
* (element) - information about an unavailable service with the itemMultiple service status can be given for an item represented by different available/unavailable elements.
Example in DAIA/JSON
{
"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"} ]
} ]
}
Example in DAIA/XML
<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>
Example in DAIA/RDF
<id:123> a frbr:Item ;
dct:description "foo"@en ;
daia:label "bar" ;
daia:heldBy <id:abc> ;
daia:availableFor [ a dso:Presentation ] ;
daia:availableFor [ a dso:Loan ] ;
daia:availableFor [ a dso:Interloan ] ;
daia:unavailableFor [ a dso:Openaccess ] ;
<id:abc> a foaf:Organization ; dct:isPartOf [
a foaf:Organization ; dct: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 |
|
narrower in DAIA/RDF |
|
broader in DAIA/XML |
|
broader in DAIA/RDF |
|
The structure of an available
element is:
service
? (attribute) - the specific service from the Document Service Ontology (DSO). The value can be given as full URI or as simple name. A name is mapped to an URI by uppercasing the first letter and prepending the base URI xs:anyURI
.href
? (attribute) - a link to perform, register or reserve the service. Type xs:anyURI
.delay
? (attribute) - a time period of estimated delay. Use unknown
or an ISO time period. If missing, then there is probably no significant delay. Type xs:duration
or the string unknown
.message
* (element) - (error) message(s) about the specific availability status of the item.limitation
* (element) - more specific limitations of the availability status.In DAIA/XML messages and limitations can be mixed in any order.
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 http://purl.org/ontology/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).
Example in DAIA/JSON
{
"available": [ { "service":"loan", "delay":"PT2H"
}
Example in DAIA/XML
<available service="loan" delay="PT2H" />
Example in DAIA/RDF
[ ] daia:availableFor [
a dso:Loan ;
daia:delay "PT2H"^^xsd:duration
] .
The structure of an unavailable
element is identical to the structure of the available element in most cases.
href
? (attribute) - see aboveexpected
(attribute) - A time period until the service will be available again. Use unknown
or an ISO time period. If missing, then the service probably won't be available in the future. Type xs:date
or xs:dateTime
or the string unknown
.message
* (element) - see abovelimitation
* (element) - more specific limitations of the availability statusqueue?
(attribute) - the number of waiting requests for this service. Type xs:nonNegativeInteger
.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 in DAIA/JSON
{
"unavailable": [ {
"service":"presentation",
"delay":"PT4H"
} ]
}
Example in DAIA/XML
<unavailable service="presentation" delay="PT4H" />
Example in DAIA/RDF
[ ] daia:unavailableFor [
a dso:Presentation ;
daia:delay "PT4H"^^xsd:duration
] .
Messages can occur at several places in a DAIA response. The structure of a message
element is:
lang
(attribute) - a RFC 3066 language code. Type xs:language
.content
(string) - the message text, a simple string without further formatting.errno
? (attribute) - an error code (integer value). Type xs:integer
.Notes:
content
is an empty string, it should be removed in DAIA encodings. Applications may treat a missing content
as the empty string.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:
Example in DAIA/JSON
{
"message" : [ {
"content":"request failed",
"lang":"en"
} ]
}
Example in DAIA/XML
<message lang="en">request failed</message>
Example in DAIA/RDF
[ ] daia:message [
rdfs:value "request failed"@en .
]
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"). * limitation
nodes give information of limitations of the availability of an item
The data structure of all these nodes is identical and discussed below.
Data structure
id
? - a (persistent) identifier for the entity. Type xs:anyURI
.href
? - a URI linking to the entity. Type xs:anyURI
.content
? - a simple message text describing the entity.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 in DAIA/JSON and DAIA/XML
{
"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>
All DAIA documents, given in DAIA/JSON or DAIA/XML can also be expressed in RDF. The ontology used for this purpose is also called DAIA/RDF. DAIA Ontology mainly consists of a set of classes and properties from related ontologies.
DAIA ontology is based on the following RDF ontologies:
The URI namespace of DAIA Ontology is daia
is recommended. The URI of DAIA Ontology as as a whole is http://purl.org/ontology/daia.
@prefix daia: <http://purl.org/ontology/daia#> .
@base <http://purl.org/ontology/daia> .
The following namspace prefixes are used to refer to related ontologies:
@prefix dso: <http://purl.org/ontology/dso#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix ssso: <http://purl.org/ontology/ssso#> .
@prefix vann: <http://purl.org/vocab/vann/> .
In Turtle syntax, the ontology is defined as following:
<> a owl:Ontology ;
rdfs:label "Document Availability Information Ontology" ;
rdfs:label "DAIA" ;
vann:preferredNamespacePrefix "daia" .
...
ssso:ServiceEvent a owl:Class ;
rdfs:isDefinedBy <http://purl.org/ontology/ssso> .
dso:DocumentService a owl:Class ;
rdfs:subClassOf ssso:ServiceEvent ;
rdfs:isDefinedBy <http://purl.org/ontology/dso> .
dso:Loan a owl:Class ;
rdfs:subClassOf dso:DocumentService ;
rdfs:isDefinedBy <http://purl.org/ontology/dso> .
dso:Presentation a owl:Class ;
rdfs:subClassOf dso:DocumentService ;
rdfs:isDefinedBy <http://purl.org/ontology/dso> .
dso:Interloan a owl:Class ;
rdfs:subClassOf dso:DocumentService ;
rdfs:isDefinedBy <http://purl.org/ontology/dso> .
dso:OpenAccess a owl:Class ;
rdfs:subClassOf dso:DocumentService ;
rdfs:isDefinedBy <http://purl.org/ontology/dso> .
ssso:Limitation a owl:Class ;
rdfs:isDefinedBy <http://purl.org/ontology/ssso> .
ssso:limits a owl:ObjectProperty ;
rdfs:domain ssso:ServiceLimitation ;
rdfs:range ssso:ServiceEvent ;
rdfs:isDefinedBy <http://purl.org/ontology/ssso> .
ssso:limitedBy a owl:ObjectProperty ;
rdfs:domain ssso:ServiceEvent ;
rdfs:range ssso:ServiceLimitation ;
owl:inverseOf ssso:limits ;
rdfs:isDefinedBy <http://purl.org/ontology/ssso> .
A storage is a place where items are stored.
daia:Storage a owl:Class .
...
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 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 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.
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.
The main difference of this specification to DAIA 0.5 is the inclusion of DAIA/RDF which was formerly defined in a separate document. Major parts of the DAIA ontology have been moved to independent micro-ontologies, involving the change of URIs. In particular, DAIA services are now defined in the Document Service Ontology. The following URIs are deprecated:
Removed:
Moved to Document Service Ontology (DSO):
Moved to Simple Service Status Ontology (SSSO):
Moved to Holding Ontology:
Nur sure about:
The remaining DAIA/RDF classes and properties may be the core of DAIA ontology (or moved to another ontology, such as DSO?):
daia:perform, daia:baseURL ...
http://purl.org/ontology/daia/availableOf changed to http://purl.org/ontology/daia#availableOf.
http://purl.org/ontology/daia/availableFor changed to http://purl.org/ontology/daia#availableFor.
http://purl.org/ontology/daia/unavailableOf changed to http://purl.org/ontology/daia#unavailableOf.
http://purl.org/ontology/daia/unavailableFor changed to http://purl.org/ontology/daia#unavailableFor.
If department and institution have same id, the department SHOULD be ignored.