The OAI-PMH element

The oai:OAI-PMH element contains the response sent by an OAI server in response to a particular request at a specified time. For example: 2002-05-01T19:20:30Z http://an.oa.org/OAI-script ... ]]>

We can infer: There exists an OAI server &s;, whose URI is the #PCDATA value of the oai:request child. There exists a request q, which is modeled by the oai:request child element. There an OAI response r, which is identical to (not modeled by) the current oai:OAI-PMH element. There exists a moment of time t identified by the value of the oai:responseDate child element. Server &s; sent response r in response to request q at time t. Or more compactly (if also more awkwardly): The oai:OAI-PMH element was sent as an OAI response, by the server identified by the content of oai:request, in response to the request described by oai:request, at the moment denoted by oai:responseDate.

More formally: (&exists; &q; : OAI-request) (&exists; &r; : OAI-response) (&exists; &s; : OAI-server) (&exists; &t; : moment) (uri_server({string(./oai:request)}, &s;) ∧ models({./oai:request}, &q;) ∧ {.} = &r; ∧ xsd_lv(xsd:dateTime, {string(./oai:responseDate)}, &t;) ∧ served_response(&q;,&s;,&t;,&r;)) (Details of the notation are given in section .)

If we use XPointer tumblers to denote elements (as needed for the first argument of the models relation) and quoted literals to represent strings, then the example given above would generate the following sentence in logical notation: (&exists; &q; : OAI-request) (&exists; &r; : OAI-response) (&exists; &s; : OAI-server) (&exists; &t; : moment) (uri_server(http://an.oa.org/OAI-script, &s;) ∧ models(element(/1/2), &q;) ∧ element(/1) = &r; ∧ xsd_lv(xsd:dateTime, 2002-05-01T19:20:30Z, &t;) ∧ served_response(&q;,&s;,&t;,&r;))

A digression on definite descriptions

If we want to be careful to capture the meaning of the definite articles in the English paraphrase, we may be troubled by the translation above. In English, we spoke of the request, the server, and so on: the descriptions (it is implied) uniquely identify a single request, a single server. To capture this information, we can use a slightly more elaborate translation: (&exists; &q; : OAI-request) (&exists; &r; : OAI-response) (&exists; &s; : OAI-server) (&exists; &t; : moment) (uri_server({string(./oai:request)}, &s;) &tab; ∧ (∀ &x;)(uri_server({string(./oai:request)}, &x;) &implies; &x; = &s;) &tab; ∧ (∀ &x;)(uri_server(&x;, &s;) &implies; &x; = {string(./oai:request)}) ∧ models({./oai:request}, &q;) &tab; ∧ (∀ &x;)(models({./oai:request}, &x;) &implies; &x; = &q;) ∧ {.} = &r; ∧ xsd_lv(xsd:dateTime, {string(./oai:responseDate)}, &t;) &tab; ∧ (∀ &x;)(xsd_lv(xsd:dateTime, {string(./oai:responseDate)}, &x;) &implies; &x; = &t;) ∧ served_response(&q;,&s;,&t;,&r;)) Here the indented clauses have been added vis-a-vis the previous translation.

In prose, There exist an OAI request &q;, an OAI response &r;, an OAI server &s;, and a moment in time &t;, such that: The string value of the oai:request child is the URI of &s; (and there is only one such server, i.e. any server whose URI is that string value is identical to &s;, and also that server has only one URI, i.e. any URI which is the URI of &s; is that string value). The request &q; is modeled by the oai:request child (and there is only one such request). The response &r; is the same as the current (oai:OAI-PMH) element. The moment &t; is the moment identified by the string value of the oai:responseDate child, interpreted according to the usual lexical mapping of the XML Schema dateTime type (and there is only one such moment). Server &s; served response &r; to request &q; at moment &t;.

If we use the description operator (℩) introduced by Russell and used since by others (e.g. and ) to allow terms corresponding to phrases like the moment denoted by oai:responseDate to appear as arguments, we'll haveIn passing, it may be noted that this translation moves the type information associated with &q;, &s;, and &t; into the descriptions; it omits for convenience the clause ((∀ &x;)(uri_server(&x;, &s;) &implies; &x; = {string(./oai:request)})) which claims that a given server has only a single URI. (&exists; &r; : OAI-response) {.} = &r; ∧ served_response( &tab; (&descrip; &q;)(OAI-request(&q;) ∧ models({./oai:request}, &q;)), &tab; (&descrip; &s;)(OAI-server(&s;) ∧ uri_server({string(./oai:request)}, &s;) &tab;&tab;&tab;&tab; ∧ (∀ &x;)(uri_server(&x;, &s;) &implies; &x; = {string(./oai:request)})), &tab; (&descrip; &t;)(moment(&t;) ∧ xsd_lv(xsd:dateTime, {string(./oai:responseDate)}, &t;)), &tab; &r;))

Although this form of expression is more compact, some readers also find it harder to follow (as does the author), in part because replacing simple variables like &q; with expressions like (&descrip; &q;)(OAI-request(&q;) ∧ models({./oai:request}, &q;)) makes it harder to read the larger expressions in which the reference is made. An alternative which some find more legible is offered by the notation suggested by , in which &descrip; is treated as a kind of quantifier: (&exists; &r; : OAI-response) &tab; (&descrip; &q; (OAI-request(&q;) ∧ models({./oai:request}, &q;))) &tab; (&descrip; &s; (OAI-server(&s;) ∧ uri_server({string(./oai:request)}, &s;))) &tab; (&descrip; &t; (moment(&t;) ∧ xsd_lv(xsd:dateTime, {string(./oai:responseDate)}, &t;))) ((∀ &x;)(uri_server(&x;, &s;) &implies; &x; = {string(./oai:request)}) &tab; ∧ {.} = &r; &tab; ∧ served_response(&q;,&s;,&t;,&r;)) In prose paraphrase, this works out to something like There exists an OAI response &r; such that there exist (a) a unique OAI request &q; modeled by the oai:request child element, (b) a unique OAI server whose URI is the string value of the oai:request child element, and (c) a unique moment &t; which is mapped to from the string value of the oai:responseDate child using the lexical mapping for xsd:dateTime, such that server &s; served response &r; to request &q; at moment &t;.

It may be just a question of what one is accustomed to, but some readers may feel that the quantifiers have become top-heavy here.

In some cases, of course, a general knowledge of which relations are functions can eliminate the need for writing out the additional clauses, or allow us to automate the task. For example, if we adopt the axiom that(∀ &s; : OAI-server) (∀ &u; : string) (uri_server(&u;, &s;) &implies; (∀ &x;)(uri_server(&u;, &x;) &implies; &x; = &s;) ∧ (∀ &x;)(uri_server(&x;, &s;) &implies; &x; = &u;)) (i.e. both the relation uri_server and its inverse are functions), then the relative uniqueness of the arguments need not be asserted each time the relation is used. It is an empirical question, whose answer is not currently clear, whether all definite descriptions in our logical translation can be handled in this way.

In what follows, we will usually omit any attempt to capture claims of uniqueness, unless they seem particularly interesting. When we do attempt to capture them, we will use a variant on the Russell/Quine notation which attempts to retain the legibility of expressions like served_response(&q;,&s;,&t;,&r;) and which follows the convention of giving types for variables quantified by &descrip;: (&exists; &q; : OAI-request) (&exists; &r; : OAI-response) (&exists; &s; : OAI-server) (&exists; &t; : moment) ( &q; = (&descrip; &q; : OAI-request)(models({./oai:request}, &q;)) &tab; ∧ &s; = (&descrip; &s; : OAI-server)(uri_server({string(./oai:request)}, &s;)) &tab; ∧ &t; = (&descrip; &t; : moment)(xsd_lv(xsd:dateTime, {string(./oai:responseDate)}, &t;)) &tab; ∧ (∀ &x;)(uri_server(&x;, &s;) &implies; &x; = {string(./oai:request)}) &tab; ∧ {.} = &r; &tab; ∧ served_response(&q;,&s;,&t;,&r;))

The responseDate element

The oai:responseDate element indicates the date and time the response was sent. Its meaning has been captured in the rule for oai:OAI-PMH, but if we wish to have an independent rule for each element type, then we can say that from an oai:responseDate element we can infer that the response consisting of the parent oai:OAI-PMH element was sent by the responsible server at the time indicated. Formally: (&exists; &t; : moment) (&exists; &r; : OAI-response) (xsd_lv(xsd:dateTime, {string(.)}, &t;) ∧ &r; = {..} ∧ was_sent_at(&r;,&t;))

For example:2002-05-01T19:20:30Z]]>

The request element

The oai:request element indicates what request generated the enclosing oai:OAI-PMH response. The content (of simple type xsd:anyURI) gives the base URI of the request, and thus the URI we use here to identify the server.

The author is not absolutely certain, after reading the documentation, whether identifying the base URI of the request with the URI of the server is completely kosher.

The attributes document the key/value pairs of the request; there will always be a verb attribute, and in a correct request the other attributes will vary with the verb.

For example:http://arXiv.org/oai2]]>

We can infer: There is a request, which is modeled by this element. When the request is valid, the verb of the request was that given in the verb attribute, and the other key/value pairs of the request are all and only those given in the other attributes. When the request raises a badVerb or badArgument error, no key/value pairs of the request are given; the only information is the base URL of the request. When the request is not valid in some other way (i.e. it raises an error or exception condition other than badVerb or badArgument), the specification appears to leave the behavior undefined.

More formally:(&exists; &q; : OAI-request) (models({ . }, &q;) ∧ ( {string(@verb)} &neq; "" &implies; request_verb(&q;, {string(@verb)}) ) ∧ ( ( {string(@verb)} = "GetRecord" &tab; ∧ request_identifier(&q;, {string(@identifier)}) &tab; ∧ request_metadataPrefix(&q;, {string(@metadataPrefix)}) ) ∨ ( {string(@verb)} = "Identify" &tab; ∧ {count(@*)} = 0 ) ∨ ( {string(@verb)} = "ListIdentifiers" &tab; ∧ request_from(&q;, {string(@from)}) &tab; ∧ request_until(&q;, {string(@until)}) &tab; ∧ request_metadataPrefix(&q;, {string(@metadataPrefix)}) &tab; ∧ request_set(&q;, {string(@set)}) &tab; ∧ request_resumptionToken(&q;, {string(@resumptionToken)}) ) ∨ ( {string(@verb)} = "ListMetadataFormats" &tab; ∧ request_identifier(&q;, {string(@identifier)}) ) ∨ ( {string(@verb)} = "ListRecords" &tab; ∧ request_from(&q;, {string(@from)}) &tab; ∧ request_until(&q;, {string(@until)}) &tab; ∧ request_metadataPrefix(&q;, {string(@metadataPrefix)}) &tab; ∧ request_set(&q;, {string(@set)}) &tab; ∧ request_resumptionToken(&q;, {string(@resumptionToken)}) ) ∨ ( {string(@verb)} = "ListSets" &tab; ∧ request_resumptionToken(&q;, {string(@resumptionToken)}) ) )

The resumptionToken mechanism is not dealt with satisfactorily in this version of this paper.

The error element

The oai:error element appears as the third child (after responseDate and request when the request raises an error condition. For example, a request with an unknown verb might return:Only might, because although conforming processors are required to use badVerb as the value of the code attribute, the textual content of the element is not constrained. Illegal OAI verb]]>

We can infer: The request which elicited this response was invalid. The specific error was the one indicated in keyword form by the code attribute. The specific error was the one describe in natural language by the #PCDATA content, if any.

More formally:(&exists; &q; : OAI-request) (models({preceding-sibling::oai:request}, &q;) ∧ invalid(&q;) ∧ request_error(&q;, {string(@code)}) ∧ ({string(.)} &neq; "" &implies; error_nldesc(&q;, {string(.)}) ) ) )

For detailed description of the errors, see the OAI specification; we won't go into more detail about the errors here.

The GetRecord element

The oai:GetRecord element contains the response of the server to a successful request to fetch a particular metadata record.

Note that the OAI vocabulary carefully distinguishes three things: the resource described by the metadata, which might be a document held by a library or archive (e.g. an autograph letter) the item for which a record is requested the metadata record actually returned by the server The item may be thought of as a sort of abstract record; conceptually it is a constituent part of a repository, but by repository the OAI documentation means an OAI server, not the library or archive or project or other institution which might hold a collection of physical documents or similar objects and which might be running the server to provide descriptions of those objects. Each item corresponds to a single resource and may provide metadata in multiple formats. So a MARC record, a Dublin Core record, and other metadata records may share the same item identifier; a particular metadata record is uniquely identified not by the item identifier, but by the item identifier (each item is guaranteed to have one), plus the metadata prefix (an identifier for a given metadata format), plus the datestamp showing when the record was created or last changed.Strictly speaking, if the metadata record is uniquely identified by the triple (item id, metadata prefix, datestamp), then a change in the datestamp invariably denotes the creation of a new record, and so no record can ever be changed. For the sake of readers less pedantic than the author of this paper, the OAI documentation does not insist on this point.

A GetRecord request must specify an item identifier and a metadata format; the oai:GetRecord element contains an oai:record element which represents the item.

If the request is faulty (e.g. because the identifier is not known or because the requested metadata format is not available), an oai:error element is returned, not a GetRecord element. (If the particular metadata record requested has been deleted, a record will be returned with status="deleted" in the record header.) So from the existence of a GetRecord element, we can infer: The verb of the request was GetRecord. (N.B. this is redundant with the verb attribute on the oai:request element.) The request raised no error and no exception. (This may be thought redundant with the absence of an error element.) The item requested exists in the repository. The metadata format requested exists for the requested item in the repository, or did exist before the record was deleted. Note that we need, for these inferences, to be able to refer to the current response, the request which elicited the current response, the repository which emitted the current response, etc. In the paraphrase below, we assume a set of relations which pair the OAI response (the ancestor oai:OAI-PMH element) with other relevant objects.

Formally, (&exists; &q; : OAI-request) (&exists; &s; : oai-server) (&exists; &d; : string) (&exists; &i; : oai-item) (&exists; &p; : string) (&q; = (&descrip; &q; : OAI-request)(req_resp(&q;,{ancestor::oai:OAI-PMH})) &tab; &s; = (&descrip; &s; : oai-server)(resp_server({ancestor::oai:OAI-PMH}, &s;)) &tab; &d; = (&descrip; &d; : string)(request_identifier(&q;, &d;)) &tab; &i; = (&descrip; &i; : oai-item)(item_id(&i;, &d;)) &tab; &p; = (&descrip; &p; : string(&p;)(request_metadataPrefix(&q;, &p;)) ∧ request_verb(&q;, "GetRecord") ∧ errorfree(&q;) ∧ isin_repository_item(&s;, &i;) ∧ hasformat_repository_item_format(&s;, &i;, &p;) ) In addition, we know in practice that the oai:record child of oai:GetRecord contains the requested metadata record in the requested format for the requested item. But it's more convenient to capture that in the sentence schemata for the oai:record element than here.

Remaining elements

The following element types have not yet been described in this version of this document: GetRecord/record Identify Identify/*, i.e. baseURL protocolVersion adminEmail earliestDatestamp deletedRecord granularity compression description ListIdentifiers ListIdentifiers/header ListIdentifiers/resumptionToken ListMetadataFormats ListMetadataFormats/metadataFormat ListRecords ListRecords/record ListRecords/resumptionToken ListSets ListSets/set ListSets/resumptionToken record/header record/metadata record/about record/header/identifier record/header/datestamp record/header/setSpec record/header/@status metadataFormat/metadataPrefix metadataFormat/schema metadataFormat/metadataNamespace set/setSpec set/setName set/setDescription

OAI-specific types

The types assumed by the OAI vocabulary are: moment: an instant of time; in practice, moments are identified by time stamps in the usual way. OAI-request: an HTTP GET request following (or not following) the rules for OAI requests.It might be preferable to distinguish OAI-request from request, where the former is guaranteed valid. OAI-response: an XML element with the generic identifier OAI-PMH in the OAI 2.0 namespace which obeys the rules laid down in OAI-server: an OAI repository. As the OAI specification says: A repository is a network accessible server that can process the 6 OAI-PMH requests in the manner described in the OAI 2.0 specification. For our purposes, we treat repositories as uniquely identified by their URI (the base URI of an OAI request sent to that server); this should be non-controversial. It is less plausible to treat, as we do here, distinct URIs as identifying distinct servers. But there is no way, within an OAI message, to make any claims about whether two OAI servers are or are not the same.Is this true? OAI-harvester: a consumer of OAI data. Within a given request/response interaction, typically the client of an OAI server. It is clear (e.g. from the discussion of provenance statements in section 2.5 of ) that the same institution may run both a server (repository) and a harvester, possibly in the same executable. For purposes of this paper, however, the reader can assume that within any given transaction (at least) the server and the client are different pieces of software.

This list is incomplete; the plan is to add to it gradually as the skeleton sentences require more entries.

Other types

In addition, there are a few types we need to define our expression language, or to define signatures of relations: attribute: an attribute of an XML element; typically denoted by an XPath expression. element: an XML element; typically denoted by an XPath expression. expandedName: a pair consisting of a URI and an XML NCName; what a qualified name (QName) expands to in context (, ). object: any kind of thing at all. xsd:string: a string of characters (here, in practice, invariably a string of Unicode characters). value: a member of the value space of some XML Schema datatype.

Primitive relations

The rules of interpretation given in section appeal to a number of primitive relations. It is hoped that the nature of the relations has been clear enough from context to allow the reader to follow the rules of interpretation; the following list gives a natural-language description of each relation.

Derivable relations

Some relations used in the rules of interpretation are implied by others. These are: errorfree (OAI-request): holds when the request has no errors; the complement of invalid. Definable as: (∀ &q; : OAI-request)(errorfree(&q;) ⇔ ¬invalid(&q;)) was_sent_at (OAI-response × moment): The OAI-response was sent at the specified moment. Derivable:(∀ &q; : OAI-request) (∀ &s; : OAI-server) (∀ &t; : moment) (∀ &r; : OAI-response) (served_response(&q;,&s;,&t;,&r;) &implies; was_sent_at(&r;,&t;))