	The Open Archives Initiative Protocol for Metadata Harvesting
	Protocol Version 1.1 of 2001-07-02 Document Version 2001-06-20 http://www.openarchives.org/OAI/openarchivesprotocol.htm Previous version: Protocol Version 1.0 of 2001-01-21 Instructions for migrating from Version 1.0 to 1.1

Editors

Herbert Van de Sompel <herbertv@cs.cornell.edu> -- Cornell University - Computer Science
Carl Lagoze <lagoze@cs.cornell.edu> -- Cornell University - Computer Science

Table of Contents

Introduction
Definitions and Concepts
    Repository
    Record
    Unique Identifier
    Datestamp
    Set
Protocol Features
    HTTP embedding of OAI requests
        HTTP Request Format
        HTTP Response Format
    Dates and Times
    Metadata Prefix and Metadata Schema
    Flow Control
Protocol Requests and Responses
    GetRecord
    Identify
    ListIdentifiers
    ListMetadataFormats
    ListRecords
    ListSets
Appendix 1: Sample XML Schema for metadata formats
    Dublin Core
    rfc1807
    oai_marc
Appendix 2: Sample XML Schema for description part of reply to Identify request
   description for repositories that share the OAI format for unique identifiers of records
   description for repositories in the e-print community
Acknowledgements

1. Introduction

The goal of the Open Archives Initiative Protocol for Metadata Harvesting (referred to as the OAI protocol in the remainder of this document) is to supply and promote an application-independent interoperability framework that can be used by a variety of communities who are engaged in publishing content on the Web. The OAI protocol described in this document permits metadata harvesting. The result is an interoperability framework with two classes of participants:

Data Providers administer systems that support the OAI protocol as a means of exposing metadata about the content in their systems;
Service Providers issue OAI protocol requests to the systems of data providers and use the returned metadata as a basis for building value-added services.

2. Definitions and Concepts

2.1 Repository

A repository is a network accessible server to which OAI protocol requests, embedded in HTTP, can be submitted. The OAI protocol provides access to metadata from OAI-compliant repositories. This metadata is output in the form of a record. A record is the result of a protocol request issued to the repository to disseminate metadata from an item. An item can be considered a constituent of the repository. The nature of an item -- for example, what type of metadata is actually stored in the item, what type is derived on-the-fly, and whether the item includes the "full content" described by the metadata -- is outside the scope of the OAI protocol. All uses of the term repository in the remainder of this document should be interpreted as an OAI-compliant repository.

2.2 Record

A record is an XML-encoded byte stream that is returned by a repository in response to an OAI protocol request for metadata from an item in that repository. OAI records -- referred to for the remainder of this document as records -- are organized into the following parts:

header -- information that is common to all records and that is necessary for the harvesting process. This information is independent of the metadata format disseminated in the record. The header consists of two parts:

the unique identifier -- the key for extracting metadata from an item in a repository;
the datestamp -- the date of creation, deletion, or latest date of modification of an item, the effect of which is a change in the metadata of a record disseminated from that item.

metadata -- a single manifestation of the metadata from an item. The OAI protocol supports multiple manifestations (formats) of metadata for any single item. At a minimum, repositories must be able to return records with metadata expressed in the Dublin Core format, without any qualification. Optionally, a repository may also be capable of disseminating other formats of metadata. The specific manifestation that should be returned in a record is specified by means of an argument -- the metadata prefix -- in the GetRecord or ListRecords protocol request that produces the record. The ListMetadataFormats protocol request returns the list of metadata formats available from a repository, or from a specific item (which can be specified as an argument to the ListMetadataFormats service request).
about -- an optional container to hold data about the metadata part of the record. Typically, the about container could be used to hold rights information regarding the metadata part of the record, terms and conditions for usage of the metadata part of the record, etc. The internal structure of the about container is not defined by the protocol. It is left to individual communities to decide on its syntax and semantics.

The example shows a record and its components:

the header part with:
- a unique identifier equal to oai:arXiv:quant-ph/9901001;
- a datestamp equal to 1999-01-01;
the metadata part expressed in unqualified Dublin Core. Note that the root element within the metadata part includes three attributes:
- xmlns -- the value of which is the namespace URI (as defined by the XML namespace specification) of the metadata that follows in this part.
- xmlns:xsi -- the value of which must always be the URI shown in the example, which is the namespace URI for XML schema.
- xsi:schemaLocation -- the value of which is a pair, the first part is the namespace URI (as defined by the XML namespace specification) of the metadata that follows in this part, and the second part is the URL of the XML schema for validation of the metadata.
the about part of the record which uses a -- fictional -- eprints-about.xsd schema as a means to express properties of the metadata part of the record. Note that the root element within the about part includes three attributes:
- xmlns -- the value of which is the namespace URI (as defined by the XML namespace specification) of the XML elements that follow in this part.
- xmlns:xsi -- the value of which must always be the URI shown in the example, which is the namespace URI for XML schema.
- xsi:schemaLocation -- the value of which is a pair, the first part is the namespace URI (as defined by the XML namespace specification) of the elements that follow in this part, and the second part is the URL of the XML schema for validation of the about part.

  <header>

   <identifier>oai:arXiv:quant-ph/9901001</identifier>

   <datestamp>1999-01-01</datestamp>

  </header>

  <metadata>

   <dc xmlns="http://purl.org/dc/elements/1.1/" 

       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

       xsi:schemaLocation="http://purl.org/dc/elements/1.1/

                           http://www.openarchives.org/OAI/1.1/dc.xsd">

    <title>Quantum slow motion</title>

    <creator>Hug, M.</creator>

    <creator>Milburn, G. J.</creator>

    <description>We simulate the center of mass motion of cold atoms in a 
     standing, amplitude modulated, laser field as an example of a system
     that has a classical mixed phase-space.</description>

    <date>1999-01-01</date>

    <type>e-print</type>

    <identifier>http://arXiv.org/abs/quant-ph/9901001</identifier>

   </dc>

  </metadata>

  <about>

   <ea xmlns="http://www.arXiv.org/eprints-about"

       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

       xsi:schemaLocation="http://www.arXiv.org/eprints-about

                           http://www.arXiv.org/eprints-about.xsd">

    <archive>The Los Alamos arXiv</archive>

    <usage>Metadata may be used without restrictions as long as the OAI 
     identifier remains attached to it.</usage>

   </ea>

  </about>

The protocol supports the notion of a deleted record, which may be used by repositories as follows. When returning a harvested record or identifier of a record, the ListRecords and ListIdentifiers service requests may indicate a status of "deleted". This status means that an item has been deleted and therefore no record can be disseminated from it. The length of time that a given repository keeps track of deleted items is not defined by the protocol. Therefore, the only guaranteed method in the protocol for determining whether a record can be returned by a repository (its corresponding item still exists) is through the GetRecord service request.

2.3 Unique Identifier

A unique identifier is a key for extracting metadata from an item in a repository. The OAI protocol specifies that each item may disseminate metadata in multiple formats. All of the members of this group of possible metadata formats disseminated from a single item share the same unique identifier. Each record disseminated by a GetRecord or ListRecords protocol request is identified by the combination of this unique identifier and a metadata prefix, which identifies the metadata format.

The format of unique identifiers corresponds to that of the URI (Uniform Resource Identifier) syntax. An individual community may develop a URI scheme for coordinated use across its repositories. For an example, see the format for identifiers proposed in Appendix 2.

These unique identifiers play two roles in the protocol:

Identifiers are returned by both the ListIdentifiers and ListRecords requests; they can be used as keys to request metadata from items.
An identifier, in combination with a metadata prefix, is used in the GetRecord protocol request as a means of requesting a record with a specific metadata format from an item. This means that the resulting record is identified by the combination of the identifier and the metadata prefix.

Note that the identifier described here is not that of the item. The nature of the item identifier is outside the scope of the OAI protocol.

Since many clients of the OAI protocol may want to access the content associated with harvested metadata, it is highly recommended that repositories use an element in metadata records to establish a linkage between the record (and its identifier) and the identifier (URL, URN, DOI, etc.) of the associated item. The mandatory Dublin Core format provides the identifier element that can be used for this purpose.

2.4 Datestamp

A datestamp is the date of creation, deletion, or latest date of modification of an item, the effect of which is a change in the metadata of a record disseminated from that item. Every record returned by the GetRecord and ListRecords service requests contains its respective datestamp in the header. Datestamps are used as values of optional arguments -- until or from -- to the ListRecords and ListIdentifiers requests to specify selective harvesting (by date) from the repository. The value of a datestamp must comply to the specifications for dates in the OAI protocol.

2.5 Set

A set is an optional construct for grouping items in a repository for the purpose of selective harvesting of records. Each repository may define a hierarchical organization of items; the hierarchy can have several top-level nodes. Each node in the hierarchy is a Set, which has:

a setTag -- a non-space separated string of alphanumeric characters;
a setSpec -- a colon [:] separated list of setTags of each node on the path leading from a root element to the actual node;
a setName -- a string useful for display purposes.

The following is an example of a possible Set hierarchy in a repository:

Institutions
- Oceanside University of Nebraska

Valley View University of Florida

Subjects

Existential Kenesiology
Quantum Psychology

The following table shows a representation of the above Set hierarchy by means of setNames, setTags and setSpecs :

setName	setTag	setSpec
Institutions	institution	institution
Oceanside University of Nebraska	nebraska	institution:nebraska
Valley View University of Florida	florida	institution:florida
Subjects	subject	subject
Existential Kenesiology	kenesiology	subject:kenesiology
Quantum Psychology	quantum	subject:quantum

Each item in a repository may be organized in one Set, several Sets, or no Sets at all. A client should not assume that harvesting every Set in a repository will retrieve records for every item in the repository. Items may also be organized in interior nodes in the Set hierarchy. Thus, in the example above, it is conceivable that an individual item is organized in both subject and florida.

The actual meaning of a Set or of the arrangement of Sets in a repository is not defined in the protocol, nor is there any way to derive this meaning through the protocol. It is expected that individual communities who use the OAI protocol may formulate well-defined Set configurations with perhaps a controlled vocabulary for Set names, and may even develop mechanisms for exposing these to service providers. For example, a group of cooperating e-print archives in a specific discipline may agree on Sets that arrange items in their repositories based on a controlled subject classification. Note that there is no mechanism for "reverse lookup"; that is, determining the Set or Sets that an item -- from which a record was disseminated -- is organized in.

A repository's Set hierarchy is represented in the protocol via setSpecs. ListSets returns the configuration of Sets in a repository as a list of setSpecs. Any of these setSpecs can be used as optional arguments to ListRecords or ListIdentifiers to specify the target Set for selective harvesting from the repository. In the previous example of a Set hierarchy, the setSpec institution:nebraska can be used in a protocol request to return only those records that are disseminated from items organized in the Set represented by this setSpec. Three issues should be noted here:

As described above an individual item may be organized in more than one Set; meaning that different setSpec arguments may return the same record(s).
As described above an individual item may not be organized in any Set; meaning that an exhaustive repetition of ListRecords requests with all possible setSpecs will not return all records in the repository. The only guaranteed method of returning all records is a ListRecords or ListIdentifiers request with no setSpec argument.
Using a setSpec as an argument in a protocol request will return:
- all records from items in the Set specified by the setSpec,
- all records from items in Sets that are descendent from the Set specified by the setSpec.
Using the previous example of a Set hierarchy, a setSpec of institution to the ListRecords protocol request will return all records from items organized within the institution Set and within the descendent Sets florida and nebraska.

3.0 Protocol Features

3.1 HTTP embedding of OAI requests

OAI protocol requests are expressed as HTTP requests. A typical implementation uses a standard Web server, such as Apache, that is configured to dispatch OAI requests to the software handling these requests. The remainder of this section describes the aspects of the protocol that are specific to the HTTP embedding.

3.1.1 HTTP Request Format

OAI protocol requests may be expressed using either the HTTP GET or POST methods. There is a single base URL, BASE-URL, for all requests. At a minimum, the BASE-URL specifies the Internet host and port of an HTTP server acting as a repository. Typically, the BASE-URL will also specify a path that is specified by the respective HTTP server as the handler for OAI protocol requests. Note that the composition of this path and its presence or absence is determined by the configuration of the repository's HTTP server.

In addition to the BASE-URL, all requests consist of a list of keyword arguments, which take the form key=value pairs. Arguments may appear in any order and multiple arguments should be separated by ampersands [&]. At a minimum, each OAI protocol request has one key=value pair that specifies the OAI protocol request issued by the client:

key is the string 'verb';
value is one of the defined OAI protocol requests.

The number and nature of additional key=value pairs is dependent on the arguments for the individual protocol request.

Libraries such as libwww-perl will decode GET and POST requests seamlessly; the application does not even need to know which method was used. The advantage of POST is that there are no limitations on the length of the arguments.

3.1.1.1 Encoding an OAI protocol request in a URL for an HTTP GET

URLs for GET requests have keyword arguments appended to the BASE-URL, separated by a question mark [?]. For example, the URL of a GetRecord protocol request to a repository with BASE-URL that is http://an.oa.org/OAI-script might be:

http://an.oa.org/OAI-script?
verb=GetRecord&identifier=oai:arXiv:hep-th/9901001&metadataPrefix=oai_dc

However, since special characters in URIs must be encoded, the valid form of the above above GET request URL is:

http://an.oa.org/OAI-script?
verb=GetRecord&identifier=oai%3AarXiv%3Ahep-th%2F9901001&metadataPrefix=oai_dc

3.1.1.2 Encoding an OAI protocol request in an HTTP POST

The keyword arguments for an OAI protocol request are carried in the message body of the HTTP POST. The Content-Type of the request should be application/x-www-form-urlencoded. For example, submitting the same request as above using the POST method would use just BASE-URL as the URL, with the format of the POST being:

POST http://an.oa.org/OAI-script HTTP/1.0
Content-Length: 78
Content-Type: application/x-www-form-urlencoded
verb=GetRecord&identifier=oai%3AarXiv%3Ahep-th%2F9901001&metadataPrefix=oai_dc

3.1.1.3 Encoding of special characters in keyword arguments of OAI protocol requests

The syntax rules for URIs restrict a few characters to special roles in certain contexts, and require that if these characters are used in any other way that they be written as an escape sequence, i.e. a percent sign followed by the character code in hexadecimal. The reserved characters include:


Character	URI Role	Escape Sequence
/	Path Component Separator	%2F
?	Query Component Separator	%3F
#	Fragment Identifier	%23
=	Name/Value Separator	%3D
&	Argument Separator in Query Component	%26
:	Host Port Separator	%3A
;	Authority Namespace Separator	%3B
' '	Space Character	%20
%	Escape Indicator	%25
+	Escaped Space	%2B

As a result, these characters must be represented by their respective escape sequence if their use does not correspond to their established URI role. In case of the OAI protocol, this means that the reserved characters have to be encoded when they in the value part of the key=value pairs of which the list of keyword arguments of the OAI protocol request consists. This applies for both the GET and POST encoding of the OAI protocol requests.

3.1.2 HTTP Response Format

Responses to protocol requests are formatted as HTTP responses, with appropriate HTTP header fields. Every OAI protocol request returns a Content-Type of text/xml. Similarly, the success or error status of each protocol request is returned via the HTTP Status-Code.

3.1.2.1 Content-Type

The Content-Type returned for all OAI protocol requests is text/xml. Encoding of the XML is done using the UTF-8 representation of Unicode, whereby:

The use of character references is preferred over the use of entity references. Character references allow XML responses to be treated as stand-alone documents that can be manipulated without dependency on entity declarations external to the document.
The use of a hexadecimal representation of character references is preferred over decimal representations, since Unicode character encodings are defined using hex numbers. For instance, © is preferred over © for encoding © .

The XML data for all responses has the following common markup:

The first tag output is an XML declaration where the version is always 1.0 and the encoding is always UTF-8, eg: <?xml version="1.0" encoding="UTF-8" ?>
The remaining content is enclosed in a root element that has the same name as the verb of the respective OAI protocol request. As shown, this element has three attributes:
- xmlns -- the value of which is the namespace URI (as defined by the XML namespace specification) of the actual OAI protocol request (refer to the documentation of each protocol request for that URI).
- xmlns:xsi -- the value of which must always be the URI shown the example, which is the namespace URI for XML schema.
- xsi:schemaLocation -- is a pair, the first part is the namespace URI (as defined by the XML namespace specification) of the protocol request, and the second part is the URL of the XML schema for validation of the response.
For all responses, the first two children of the root element are:
- responseDate -- a timestamp (compliant with the dates and times specifications) indicating the time and date that the response was sent. This must be expressed in the local time of the repository.
- requestURL -- the URL for an HTTP GET request that could be used to re-submit the protocol request that generated this response. Note that this URL is encoded exactly as in protocol requests. In addition, in the encoded URL all ampersand characters (&) that are used to separate arguments must be encoded as & in order to obtain valid XML.

For example, the reply to the GetRecord protocol request shown above will be of the form:

<?xml version="1.0" encoding="UTF-8" ?>
<GetRecord
    xmlns="http://www.openarchives.org/OAI/1.1/OAI_GetRecord"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_GetRecord
                http://www.openarchives.org/OAI/1.1/OAI_GetRecord.xsd">
  <responseDate>2001-06-01T19:20:30-04:00</responseDate>
  <requestURL>http://an.oa.org/OAI-script?verb=GetRecord
              &identifier=oai%3AarXiv%3Ahep-th%2F9901001
              &metadataPrefix=oai_dc</requestURL>
     list of records
</GetRecord>

3.1.2.2 Status-Code

The OAI protocol uses the HTTP Status-Code to indicate the success or nature of the failure of the request. A normal response to an OAI protocol request is signaled with the HTTP 200 Status-Code. Error returns are signaled with the appropriate 4xx code as specified in the HTTP protocol. The following HTTP Status-Code has a special meaning when returned in the context of responses to OAI protocol requests:

400 - a Status-Code of 400 is returned when the syntax of the protocol request is illegal, i.e.:
- illegal verbs are used in the request;
- illegal arguments are used in the request.

OAI compliant repositories may also employ other HTTP Status-Codes in manners as defined by the HTTP protocol. The following list includes Status-Codes that may be useful for load balancing of OAI repositories:

302 - Allows the repository to temporarily redirect an OAI protocol request to another repository. The URI of the temporary repository should be given by the Location field in the HTTP response.
503 - Service unavailable, a Retry-After period is specified. Clients should wait this period before attempting another OAI protocol request (Clients that do not observe the Retry-After period may be denied access).

Repositories should use the HTTP Reason-Phrase to provide additional information about an error that is useful to a human reader.

3.2 Dates and Times

Dates and times are uniformly encoded throughout the protocol. Their use is as follows:

Protocol Requests: Values for the optional from and until arguments in ListIdentifiers and ListRecords protocol requests, as well as for datestamps in the headers of records are encoded using the "Complete date" variant of ISO8601. That format is YYYY-MM-DD where YYYY is the year, MM is the month of the year between 01 (January) and 12 (December), and DD is the day of the month between 01 and 28 or 29 or 30 or 31, depending on length of month and whether it is a leap year. For example: 1957-03-20 is March 20th 1957.
Protocol Responses: Each protocol response includes a responseDate element, which must be the time and date of the response in the local time of the repository. This is encoded using the "Complete date plus hours, minutes and seconds" variant of ISO8601. That format is YYYY-MM-DDThh:mm:ssTZD, with the following meanings:
- YYYY, MMM, DD is the same as for dates.
- T is the character "T",
- hh are the hours (between 00 and 23), mm are the minutes (between 00 and 59) and ss the seconds (between 00 and 59).
- TZD is an indication of the time zone of the repository, expressed as an offset from UTC. A time zone offset of "+hh:mm" indicates that the date/time uses a local time zone which is "hh" hours and "mm" minutes ahead of UTC. A time zone offset of "-hh:mm" indicates that the date/time uses a local time zone which is "hh" hours and "mm" minutes behind UTC.
For instance, 1957-03-20T20:30:00+00:00 is UTC 8:30 PM on March 20th 1957.

3.3 Metadata Prefix and Metadata Schema

Each metadata format that is included in records disseminated by the OAI protocol is identified within the protocol requests to a repository by a metadata prefix and across multiple repositories by the URL of a metadata schema:

The metadata prefix must be a non-space embedded string consisting of alphanumeric characters or an underscore [_] character. For the purpose of clarity in this document, all metadata prefixes will be preceded by the string oai_ (for example, oai_dc).
The metadata schema is an XML schema that may be used as a test of conformance of the metadata included in the record. It is highly recommended that the schema include comments that aid in human understandability.

The metadata formats that are available for a repository (or for a specific identifier) can be obtained through the ListMetadataFormats protocol request. For each metadata format that is supported, the response to the ListMetadataFormats protocol requests contains the metadata prefix of the format and the URL of the metadata schema for the metadata format. Optionally, this response may also contain the XML namespace URI associated with the format.

Metadata prefixes are used in the ListRecords and GetRecord protocol requests, to request records that include metadata in the format identified by the metadata prefix.

The metadata in each record returned by ListRecords and GetRecord complies to the conventions of the XML namespace specification. This means that the root element of the metadata part must contain an xmlns attribute, the value of which is the namespace URI of the metadata format. The root element should also contain an xsi:schemaLocation attribute that has a value that includes the URL of the XML schema for validation of the metadata. This URL should match the URL of the metadata schema for the metadata prefix included as an argument to the ListRecords or GetRecord request (the mapping from metadata prefix to metadata schema is defined by the repository's response to the ListMetadataFormats protocol request).

The OAI protocol mandates one required metadata format for the purpose of interoperability. This format is Dublin Core, without any qualification. Therefore, the protocol reserves the metadata prefix 'oai_dc', and the URL of a metadata schema for unqualified Dublin Core, which is http://www.openarchives.org/OAI/1.1/dc.xsd.

Certain communities may adopt guidelines for sharing of metadata prefixes and/or metadata schema throughout the community. Such guidelines are outside of the scope of the OAI protocol.

Appendix 1 provides some sample XML Schema and instance documents for common metadata formats such as Dublin Core, MARC and RFC1807

3.4 Flow Control

A number of OAI protocol requests return a list of discrete entities; ListRecords returns a list of records, ListIdentifiers returns a list of identifiers, and ListSets returns a list of setSpecs. In some cases, these lists may be large and it may be practical to partition them among a series of protocol requests and responses. This partitioning is accomplished as follows:

A repository replies to a protocol request with an incomplete list and a resumptionToken;
In order to make the response a complete list, the client will need to issue one or more protocol requests with resumptionTokens as arguments. A complete response then consists of the combination of the incomplete lists from the sequence of protocol requests.

The details on flow control and the resumptionToken are as follows:

The only defined use of resumptionToken is as follows:
- a client receives a resumptionToken from a repository as part of a reply to a protocol request;
- the client copies the resumptionToken and includes it in a subsequent protocol request.
All other uses of resumptionToken by a client are illegal and hence will return a Status-Code of 400 from the repository.
In all cases when a resumptionToken is issued, the incomplete list will always consist of complete entities; e.g., all individual records returned in an incomplete record list from a ListRecords request will be intact.
The format of the resumptionToken is undefined by the OAI protocol and should be considered opaque by the client.
The protocol does not define the semantics of incompleteness. Therefore, a client should not assume that the members in an incomplete list conform to some selection criteria (e.g., date ordering).
The time-to-live of an individual resumptionToken is undefined by the OAI protocol. It is conceivable that there will be instances when a repository considers an individual resumptionToken extinct; i.e. the time span between the issuance of the resumptionToken and its use in a subsequent request is "too long". In that case, the request will return a Status-Code of 400 (illegal arguments) and the client will need to reinitiate the sequence of requests (and dispose of the existing incomplete list). Since the format of a resumptionToken is opaque, there is no defined way for a client to determine its time-to-live.
Before including a resumptionToken in a subsequent request, a client should encode any special characters in it.

The use of the resumptionToken in the context of a series of ListRecords requests is as follows:

The response to a ListRecords protocol request consists of a record list (a list of records). This record list is distinguished as incomplete -- in contrast to complete -- if the response to the ListRecords protocol request includes a resumptionToken.
If a record list is incomplete, the client should include the resumptionToken as the only argument to a subsequent ListRecords request. The response to this request is a continuation of the incomplete record list that resulted from the ListRecords protocol request that issued the resumptionToken. The client may then merge the records from the continuation with the incomplete record list.
This subsequent request may itself result in a reply that contains a resumptionToken. The client should then continue to issue ListRecord requests using the resumptionToken from the previous request, merging returned records with the incomplete record list until a reply does no longer contain a resumptionToken. The absence of a resumptionToken informs the client that all records that make up a complete record list have been gathered.

This flow control mechanism, in combination with the 503 Status-Code, provides some basic tools with which a repository can enforce an acceptable use policy for its harvesting interface. Communities implementing the OAI protocol may need more extensive tools to enforce acceptable use policies for either the harvesting interface of their repositories or for the metadata harvested from those repositories. The enforcement of such additional policies is outside of the scope of the OAI protocol.

4. Protocol Requests and Responses

This section lists the protocol requests -- verbs -- defined in the Open Archives Initiative protocol. The documentation for each protocol request is organized as follows:

Each section header corresponds to the token used to specify the request as the required verb argument to an HTTP protocol request.
A brief summary of the meaning of the verb and notes on its usage
The list of additional arguments for the request. Arguments are of three types:
- required, the argument must be included with the request (the verb argument is always REQUIRED).
- optional, the argument may be included with the request.
- exclusive, the argument may be included with request, but must be the only argument (except for the verb argument).
The format of the response defined by means of an XML schema.
Exception conditions for the protocol request. These are in addition to the HTTP Status-Codes that have a special meaning in the context of the OAI protocol, which are listed under Status-Codes.
One or more example requests and corresponding responses, with explanatory notes if appropriate.

4.1. GetRecord

Summary and Usage Notes

This verb is used to retrieve an individual record (metadata) from an item in a repository. Required arguments specify the identifier, or key, of the requested record and the format of the metadata that should be included in the record

Arguments

identifier a REQUIRED argument that specifies the unique identifier that should be used as a key to extract the requested record from an item in the repository.
metadataPrefix a REQUIRED argument that specifies the metadata prefix of the format that should be included in the metadata part of the returned record. The value of this argument must be a non-space embedded string consisting of alphanumeric and underscore [_] characters; [A-Za-z0-9_]. The metadata formats supported by a repository and for a particular record can be retrieved using the ListMetadataFormats request.

Exception Conditions

Identifier does not exist - The response will not contain a record container.
Metadata format can not be disseminated for the identifier - The record in the response contains a header but no metadata container.

Response Format

A XML schema for validating the response is as follows:

<schema xmlns="http://www.w3.org/2001/XMLSchema"

        xmlns:oai="http://www.openarchives.org/OAI/1.1/OAI_GetRecord"

        targetNamespace="http://www.openarchives.org/OAI/1.1/OAI_GetRecord"

        elementFormDefault="qualified"

        attributeFormDefault="unqualified">



<annotation>

 <documentation>

   Schema to verify validity of responses to GetRecord OAI-protocol request.

   This Schema validated at http://www.w3.org/2001/03/webdata/xsv on 2001-05-07

   with XSV XSV 1.189/1.95 of 2001/05/07 08:38:12

 </documentation>

</annotation>



<element name="GetRecord" type="oai:GetRecordType"/>



<!-- response to GetRecord-request -->



<complexType name="GetRecordType">

 <sequence>

   <element name="responseDate" minOccurs="1" maxOccurs="1" type="dateTime"/>

   <element name="requestURL" minOccurs="1" maxOccurs="1" type="anyURI"/>

   <element name="record" minOccurs="0" maxOccurs="1" type="oai:recordType"/>

 </sequence>

</complexType>



<!-- define recordType -->

<!-- a record has a header and a metadata part -->



<complexType name="recordType">

 <sequence>

   <element name="header" minOccurs="1" maxOccurs="1" type="oai:headerType"/>

   <element name="metadata" minOccurs="0" maxOccurs="1" type="oai:metadataType"/>

   <element name="about" minOccurs="0" maxOccurs="1" type="oai:aboutType"/>

 </sequence>

    <attribute name="status" use="optional" type="oai:statusType"/>

</complexType>



<!-- define headerType -->

<!-- a header has a unique identifier and a datestamp -->



<complexType name="headerType">

 <sequence>

   <element name="identifier" minOccurs="1" maxOccurs="1" type="anyURI"/>

   <element name="datestamp" minOccurs="1" maxOccurs="1" type="date"/>

 </sequence>

</complexType>



<!-- define metadataType -->

<!-- metadata must be expressed in XML that is compliant with another XML  -->

<!-- Schema. metadata must be explicitly qualified in the response -->



<complexType name="metadataType">

 <sequence>

  <any namespace="##other" processContents="lax"/>

 </sequence>

</complexType>



<!-- define aboutType -->

<!-- data "about" the record must be expressed in XML -->

<!-- that is compliant with an XML Schema defined by a community -->



<complexType name="aboutType">

 <sequence>

  <any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="1"/>

 </sequence>

</complexType>



 <!-- define statusType -->
 <!-- a record can have a status of "deleted" . -->

<simpleType name="statusType">

  <restriction base="string">

   <enumeration value="deleted"/>

  </restriction>

</simpleType>





</schema>

This Schema is available at http://www.openarchives.org/OAI/1.1/OAI_GetRecord.xsd

Examples

Request

Request a record in the Dublin Core metadata format [URL shown without encoding for better readability].

http://an.oa.org/OAI-script?

       verb=GetRecord&identifier=oai:arXiv:quant-ph/9901001&metadataPrefix=oai_dc

Response

<?xml version="1.0" encoding="UTF-8"?>

 <GetRecord 
    xmlns="http://www.openarchives.org/OAI/1.1/OAI_GetRecord"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_GetRecord         

                  http://www.openarchives.org/OAI/1.1/OAI_GetRecord.xsd">

  <responseDate>2001-06-10T14:09:57-07:00</responseDate>

  <requestURL>http://an.oa.org/OAI-script?verb=GetRecord
              &amp;identifier=oai%3AarXiv%3Aquant-ph%2F9901001
              &amp;metadataPrefix=oai_dc</requestURL>

  <record>

   <header>

    <identifier>oai:arXiv:quant-ph/9901001</identifier>

    <datestamp>1999-01-01</datestamp>

   </header>

   <metadata>

   <dc xmlns="http://purl.org/dc/elements/1.1/" 

       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

       xsi:schemaLocation="http://purl.org/dc/elements/1.1/

                           http://www.openarchives.org/OAI/1.1/dc.xsd">

     <title>Quantum slow motion</title>

     <creator>Hug, M.</creator>

     <creator>Milburn, G. J.</creator>

     <description>We simulate the center of mass motion of cold atoms in a standing, 
      amplitude modulated, laser field as an example of a system that has a classical 

      mixed phase-space.</description>

     <date>1999-01-01</date>

     <type>e-print</type>

     <identifier>http://arXiv.org/abs/quant-ph/9901001</identifier>

    </dc>

   </metadata>

  </record>

 </GetRecord>

Request

Request a record in the Dublin Core metadata format. The requested record, however, can not be returned because the identifier does not exist. Therefore, the response does not contain a record container [URL shown without encoding for better readability].

http://an.oa.org/OAI-script?

       verb=GetRecord&identifier=oai:arXiv:quant-ph/0201001&metadataPrefix=oai_dc

Response

<?xml version="1.0" encoding="UTF-8"?>

 <GetRecord 
    xmlns="http://www.openarchives.org/OAI/1.1/OAI_GetRecord"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_GetRecord         

                  http://www.openarchives.org/OAI/1.1/OAI_GetRecord.xsd">

  <responseDate>2001-06-10T14:09:57-07:00</responseDate>

  <requestURL>http://an.oa.org/OAI-script?verb=GetRecord
              &amp;identifier=oai%3AarXiv%3Aquant-ph%2F0201001
              &amp;metadataPrefix=oai_dc</requestURL>

 </GetRecord>

Request

Request a record in the oai_marc metadata format. However, the requested metadata format can not be disseminated for this identifier. Therefore, the response record contains a header but no metadata container [URL shown without encoding for better readability].

http://an.oa.org/OAI-script?

       verb=GetRecord&identifier=oai:arXiv:quant-ph/9901001&metadataPrefix=oai_marc

Response

<?xml version="1.0" encoding="UTF-8"?>

 <GetRecord 
    xmlns="http://www.openarchives.org/OAI/1.1/OAI_GetRecord"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_GetRecord         

                  http://www.openarchives.org/OAI/1.1/OAI_GetRecord.xsd">

  <responseDate>2001-06-10T14:09:57-07:00</responseDate>

  <requestURL>http://an.oa.org/OAI-script?verb=GetRecord
              &amp;identifier=oai%3AarXiv%3Aquant-ph%2F9901001
              &amp;metadataPrefix=oai_marc</requestURL>

  <record>

   <header>

    <identifier>oai:arXiv:quant-ph/9901001</identifier>

    <datestamp>1999-01-01</datestamp>

   </header>

  </record>

 </GetRecord>

4.2. Identify

Summary and Usage Notes

This verb is used to retrieve information about a repository, including administrative, identity, and community-specific information.

Arguments

None

Exception Conditions

None

Response Format

A XML schema for validating the response is as follows:

<schema xmlns="http://www.w3.org/2001/XMLSchema"

        xmlns:oai="http://www.openarchives.org/OAI/1.1/OAI_Identify"

        targetNamespace="http://www.openarchives.org/OAI/1.1/OAI_Identify"

        elementFormDefault="qualified"

        attributeFormDefault="unqualified">



<annotation>

 <documentation>

   Schema to verify validity of responses to Identify OAI-protocol request.

   This Schema validated at http://www.w3.org/2001/03/webdata/xsv on 2001-05-07

   with XSV XSV 1.189/1.95 of 2001/05/07 08:38:12

 </documentation>

</annotation>



<element name="Identify" type="oai:IdentifyType"/>



<!-- response to Identify-request -->



<complexType name="IdentifyType">

 <sequence>

   <element name="responseDate" minOccurs="1" maxOccurs="1" type="dateTime"/>

   <element name="requestURL" minOccurs="1" maxOccurs="1" type="anyURI"/>

   <element name="repositoryName" minOccurs="1" maxOccurs="1" type="string"/>

   <element name="baseURL" minOccurs="1" maxOccurs="1" type="anyURI"/>

   <element name="protocolVersion" minOccurs="1" maxOccurs="1" type="string"/>

   <element name="adminEmail" minOccurs="1" maxOccurs="1" type="anyURI"/>

   <element name="description" minOccurs="0" maxOccurs="unbounded" 
            type="oai:descriptionType"/>

 </sequence>

</complexType>



<complexType name="descriptionType">

 <sequence>

  <any namespace="##other" processContents="lax"/>

 </sequence>

</complexType>



</schema>

This Schema is available at http://www.openarchives.org/OAI/1.1/OAI_Identify.xsd

Examples

Request

http://an.oa.org/OAI-script?

       verb=Identify

Response

The response to this protocol request includes the following elements that must be provided by every OAI compliant repository:

repositoryName: a human readable name for the repository, in the example "The University of Spa E-print System";
baseURL: the BASE-URL of the repository;
protocolVersion: the version of the OAI protocol supported by the repository;
adminEmail: the e-mail address of the administrator of the repository.

In addition, the response may contain a list of description containers, which provide an extensible mechanism for communities to describe their repositories. The description container, could -- for instance -- be used to include collection-level metadata in the response to the Identify request. Each description container must be accompanied by the URL of an XML schema, which provides the semantics of the descriptive container. The below example of a response to the Identify request contains two description containers:

The oai-identifier container complies to an XML Schema, which is available at http://www.openarchives.org/OAI/1.1/oai-identifier.xsd. This schema, shown in Appendix 2, is used by repositories that choose to comply with a specific format of unique identifiers for records. The format of that identifier is explained by means of comments in the oai-identifier.xsd XML Schema.
The eprints container complies to an XML Schema, which is available at http://www.openarchives.org/OAI/1.1/eprints.xsd. This schema, shown in Appendix 2, has been agreed upon by the OAI e-print community, and contains information specific to repositories in that community.

<?xml version="1.0" encoding="UTF-8"?>

  <Identify 
     xmlns="http://www.openarchives.org/OAI/1.1/OAI_Identify"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

     xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_Identify         

                   http://www.openarchives.org/OAI/1.1/OAI_Identify.xsd">

    <responseDate>2001-06-01T19:20:30-04:00</responseDate>

    <requestURL>http://an.oa.org/OAI-script?verb=Identify</requestURL>

    <repositoryName>The University of Spa E-print System</repositoryName>

    <baseURL>http://an.oa.org/OAI-script</baseURL>

    <protocolVersion>1.1</protocolVersion>

    <adminEmail>mailto:adm&#x0040;spa.ac.be</adminEmail>

    <description>

      <oai-identifier xmlns="http://www.openarchives.org/OAI/1.1/oai-identifier"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

            xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/oai-identifier         

                          http://www.openarchives.org/OAI/1.1/oai-identifier.xsd">

        <scheme>oai</scheme>

        <repositoryIdentifier>bespa</repositoryIdentifier>

        <delimiter>:</delimiter>

        <sampleIdentifier>oai:bespa:medi99-123</sampleIdentifier>

      </oai-identifier>

    </description>

    <description>

      <eprints xmlns="http://www.openarchives.org/OAI/1.1/eprints"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

            xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/eprints         

                                http://www.openarchives.org/OAI/1.1/eprints.xsd">

        <content>

          <URL>http://an.oa.org/info/content.htm</URL>

        </content>

        <metadataPolicy>

          <text>Metadata can be used by commercial and non-commercial service
           providers</text>

          <URL>http://an.oa.org/info/metadata_use.htm</URL>

        </metadataPolicy>

        <dataPolicy>

          <text>Full content, i.e. preprints may not be harvested by robots</text>

        </dataPolicy>

        <submissionPolicy>

          <URL>http://an.oa.org/info/submission.htm</URL>

        </submissionPolicy>

      </eprints>

    </description>

  </Identify>

4.3. ListIdentifiers

Summary and Usage Notes

This verb is used to retrieve the identifiers of records that can be harvested from a repository. Optional arguments permit selectivity of the identifiers - based on their membership in a specific Set in the repository or based on their modification, creation, or deletion within a specific date range.

Arguments

until an OPTIONAL argument with a date value, which specifies that only the unique identifiers of records with a datestamp older than or equal to the specified date should be returned.
from an OPTIONAL argument with a date value, which specifies that only the unique identifiers of records with a datestamp that is more recent than or equal to the specified date should be returned.
set an OPTIONAL argument with a setSpec value, which specifies that only the unique identifiers of records from the specified Set should be returned.
resumptionToken an EXCLUSIVE argument with a value that is the flow control token returned by a previous ListIdentifiers request that issued a partial response.

Exception Conditions

No records match the request - The response will not contain any identifier elements.

Response Format

A XML schema for validating the response is as follows:

<schema xmlns="http://www.w3.org/2001/XMLSchema"

        xmlns:oai="http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers"

        targetNamespace="http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers"

        elementFormDefault="qualified"

        attributeFormDefault="unqualified">



<annotation>

 <documentation>

   Schema to verify validity of responses to ListIdentifiers OAI-protocol request.

   This Schema validated at http://www.w3.org/2001/03/webdata/xsv on 2001-05-07

   with XSV XSV 1.189/1.95 of 2001/05/07 08:38:12

 </documentation>

</annotation>



<element name="ListIdentifiers" type="oai:ListIdentifiersType"/>



<!-- response to ListIdentifiers-request -->

<!-- records have an optional "deleted" status -->

<!-- this response may contain an optional resumptionToken -->



<complexType name="ListIdentifiersType">

 <sequence>

   <element name="responseDate" minOccurs="1" maxOccurs="1" type="dateTime"/>

   <element name="requestURL" minOccurs="1" maxOccurs="1" type="anyURI"/>

   <element ref="oai:identifier" minOccurs="0" maxOccurs="unbounded"/>

   <element name="resumptionToken" minOccurs="0" maxOccurs="1" type="string"/>

 </sequence>

</complexType>



<element name="identifier">

 <complexType>

  <simpleContent>

   <extension base="anyURI">

    <attribute name="status" use="optional" type="oai:statusType"/>

   </extension>

  </simpleContent>

 </complexType>

</element>



 <!-- define statusType -->
 <!-- a record can have a status of "deleted" . -->

<simpleType name="statusType">

  <restriction base="string">

   <enumeration value="deleted"/>

  </restriction>

</simpleType>


</schema>

This Schema is available at http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers.xsd

Examples

Request

List the unique identifiers of records added or modified since January 15, 1998 in the "hep" Set of the "physics" Set [URL shown without encoding for better readability].

http://an.oa.org/OAI-script?



       verb=ListIdentifiers&from=1998-01-15&set=physics:hep

Response

A list of four identifiers is returned, one of which has a "deleted" status. In addition, a resumption token has been returned, indicating the list of identifiers is incomplete and one or more subsequent requests will need to be issued to complete the list.

<?xml version="1.0" encoding="UTF-8"?>

  <ListIdentifiers 
      xmlns="http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers         

                    http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers.xsd">

    <responseDate>2001-06-01T19:20:30-04:00</responseDate>

    <requestURL>http://an.oa.org/OAI-script?verb=ListIdentifiers
                &amp;from=1998-01-15&amp;setSpec=physics%3Ahep</requestURL>

     <identifier>oai:arXiv:hep-th/9801001</identifier>

     <identifier>oai:arXiv:hep-th/9801002</identifier>

     <identifier>oai:arXiv:hep-th/9801005</identifier>

     <identifier status="deleted">oai:arXiv:hep-th/9801010</identifier>

    <resumptionToken>xxx45abttyz</resumptionToken>

  </ListIdentifiers>

Request

Issue a subsequent request to the one issued above, with a single resumptionToken argument whose value is that returned in the previous response.

http://an.oa.org/OAI-script?

       verb=ListIdentifiers&resumptionToken=xxx45abttyz

Response

<?xml version="1.0" encoding="UTF-8"?>

  <ListIdentifiers 
      xmlns="http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers         

                    http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers.xsd">

    <responseDate>2001-06-01T19:20:30-04:00</responseDate>

    <requestURL>http://an.oa.org/OAI- script?verb=ListIdentifiers

                &amp;resumptionToken=xxx45abttyz</requestURL>

     <identifier>oai:arXiv:hep-th/9801020</identifier>

     <identifier>oai:arXiv:hep-th/9801060</identifier>

  </ListIdentifiers>

Request

List the unique identifiers of records added or modified on January 1, 2001 in the "hep" Set of the "physics" Set. There are no matches for this request, hence, the response does not contain any identifier tags [URL shown without encoding for better readability].

http://an.oa.org/OAI-script?



       verb=ListIdentifiers&from=2001-01-01&until=2001-01-01&set=physics:hep

Response

<?xml version="1.0" encoding="UTF-8"?>

  <ListIdentifiers 
      xmlns="http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers         

                    http://www.openarchives.org/OAI/1.1/OAI_ListIdentifiers.xsd">

    <responseDate>2001-06-01T19:20:30-04:00</responseDate>

    <requestURL>http://an.oa.org/OAI-script?verb=ListIdentifiers
                &amp;from=2001-01-01&amp;until=2001-01-01
                &amp;setSpec=physics%3Ahep</requestURL>

  </ListIdentifiers>

4.4. ListMetadataFormats

Summary and Usage Notes

This verb is used to retrieve the metadata formats available from a repository. An optional argument restricts the request to the formats available for a specific record.

Arguments

identifier an OPTIONAL argument that specifies the unique identifier for which available metadata formats is being requested. If this argument is omitted, then the response includes all metadata formats supported by this repository. Note that the fact that a metadata format is supported by a repository does not mean that it can be disseminated by all items in that repository.

Exception Conditions

The identifier does not exist - The response will not contain a metadataFormat container.

Response Format

A XML schema for validating the response is as follows:

<schema xmlns="http://www.w3.org/2001/XMLSchema"

  xmlns:oai="http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats"

  targetNamespace="http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats"

  elementFormDefault="qualified"

  attributeFormDefault="unqualified">



<annotation>

 <documentation>

   Schema to verify validity of responses to ListMetadataFormats OAI-protocol 

   request.

   This Schema validated at http://www.w3.org/2001/03/webdata/xsv on 2001-05-07

   with XSV XSV 1.189/1.95 of 2001/05/07 08:38:12

 </documentation>

</annotation>



<element name="ListMetadataFormats" type="oai:ListMetadataType"/>



<!-- response to ListMetadataFormats-request -->



<complexType name="ListMetadataType">

 <sequence>

    <element name="responseDate" minOccurs="1" maxOccurs="1" type="dateTime"/>

    <element name="requestURL" minOccurs="1" maxOccurs="1" type="anyURI"/>

    <element name="metadataFormat" minOccurs="0" maxOccurs="unbounded" 
             type="oai:metadataFormatType"/>

 </sequence>

</complexType>



<complexType name="metadataFormatType">

 <sequence>

   <element name="metadataPrefix" minOccurs="1" maxOccurs="1" 
            type="oai:metadataPrefixType"/>

   <element name="schema" minOccurs="1" maxOccurs="1" type="anyURI"/>

   <element name="metadataNamespace" minOccurs="0" maxOccurs="1" 
            type="anyURI"/>

 </sequence>

</complexType>



<simpleType name="metadataPrefixType">

 <restriction base="string">

   <pattern value="[a-zA-Z0-9_]+"/>

 </restriction>

</simpleType>



</schema>

This Schema is available at http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats.xsd

Examples

Request

List the metadata formats that can be disseminated from the record with unique identifier oai:arXiv:hep-th/9901001 [URL shown without encoding for better readability].

http://an.oa.org/OAI-script?

       verb=ListMetadataFormats&identifier=oai:arXiv:hep-th/9901001

Response

<?xml version="1.0" encoding="UTF-8"?>

  <ListMetadataFormats 
      xmlns="http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats         

                    http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats.xsd">

    <responseDate>2001-06-01T19:20:30-04:00</responseDate> 

    <requestURL>http://an.oa.org/OAI-script?verb=ListMetadataFormats

                &amp;identifier=oai%3AarXiv%3Ahep-th%2F9901001</requestURL>

    <metadataFormat>

      <metadataPrefix>oai_rfc1807</metadataPrefix>

      <schema>http://www.openarchives.org/OAI/1.1/rfc1807.xsd</schema>

    </metadataFormat>

    <metadataFormat>

      <metadataPrefix>oai_dc</metadataPrefix>

      <schema>http://www.openarchives.org/OAI/1.1/dc.xsd</schema>

      <metadataNamespace>http://purl.org/dc/elements/1.1/</metadataNamespace>

    </metadataFormat>

</ListMetadataFormats>

Request

List the metadata formats that can be disseminated from the repository http://an.oa.org/OAI-script.

http://an.oa.org/OAI-script?

       verb=ListMetadataFormats

Response

<?xml version="1.0" encoding="UTF-8"?>

  <ListMetadataFormats 
      xmlns="http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats         

                    http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats.xsd">

    <responseDate>2001-06-01T19:20:30-04:00</responseDate> 

    <requestURL>http://an.oa.org/OAI-script?verb=ListMetadataFormats</requestURL>

    <metadataFormat>

      <metadataPrefix>oai_rfc1807</metadataPrefix>

      <schema>http://www.openarchives.org/OAI/1.1/rfc1807.xsd</schema>

    </metadataFormat>

    <metadataFormat>

      <metadataPrefix>oai_dc</metadataPrefix>

      <schema>http://www.openarchives.org/OAI/1.1/dc.xsd</schema>

      <metadataNamespace>http://purl.org/dc/elements/1.1/</metadataNamespace>

    </metadataFormat>

    <metadataFormat>

      <metadataPrefix>oai_marc</metadataPrefix>

      <schema>http://www.openarchives.org/OAI/1.1/oai_marc.xsd</schema>

    </metadataFormat>

</ListMetadataFormats>

Request

List the metadata formats that can be disseminated from the record with unique identifier oai:arXiv:hep-th/0101001. The identifier, however, does not exist and therefore, the response does not contain a metadataFormat container. [URL shown without encoding for better readability].

http://an.oa.org/OAI-script?

       verb=ListMetadataFormats&identifier=oai:arXiv:hep-th/0101001

Response

<?xml version="1.0" encoding="UTF-8"?>

  <ListMetadataFormats 
      xmlns="http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats         

                    http://www.openarchives.org/OAI/1.1/OAI_ListMetadataFormats.xsd">

    <responseDate>2001-06-01T19:20:30-04:00</responseDate> 

    <requestURL>http://an.oa.org/OAI-script?verb=ListMetadataFormats

                &amp;identifier=oai%3AarXiv%3Ahep-th%2F0101001</requestURL>

</ListMetadataFormats>

4.5. ListRecords

Summary and Usage Notes

This verb is used to harvest records from a repository. Optional arguments permit selectivity of the harvesting - based on the membership of records in a specific Set in the repository or based on their modification, creation, or deletion within a specific date range.

Arguments

until an OPTIONAL argument with a date value, which specifies that only records with a datestamp older than or equal to the specified date should be returned.
from an OPTIONAL argument with a date value, which specifies that only records with a datestamp that is more recent than or equal to the specified date should be returned.
set an OPTIONAL argument with a setSpec value, which specifies that only records from the specified Set should be returned.
resumptionToken an EXCLUSIVE argument with a value that is the flow control token returned by a previous ListRecords request that issued a partial response.
metadataPrefix a REQUIRED argument that specifies the metadata prefix of the format that should be included in the metadata part of the returned records. The value of this argument must be a non-space embedded string consisting of alphanumeric and underscore [_] characters; [A-Za-z0-9_]. The metadata formats supported by a repository and for a particular record can be retrieved using the ListMetadataFormats request.

Exception Conditions

No records match the request - The response will not contain any record containers.
Requested metadata format can not be disseminated for a matching record - The response record contains a header but no metadata container.

Response Format

A XML schema for validating the response is as follows:

<schema xmlns="http://www.w3.org/2001/XMLSchema"

         xmlns:oai="http://www.openarchives.org/OAI/1.1/OAI_ListRecords"

         targetNamespace="http://www.openarchives.org/OAI/1.1/OAI_ListRecords"

         elementFormDefault="qualified"

         attributeFormDefault="unqualified">



 <annotation>

  <documentation>

    Schema to verify validity of responses to ListRecords OAI-protocol request.

    This Schema validated at http://www.w3.org/2001/03/webdata/xsv on 2001-05-07

    with XSV XSV 1.189/1.95 of 2001/05/07 08:38:12

  </documentation>

 </annotation>



 <element name="ListRecords" type="oai:ListRecordsType"/>



 <!-- response to ListRecords-request -->

 <!-- this response may contain an optional resumptionToken -->



 <complexType name="ListRecordsType">

  <sequence>

    <element name="responseDate" minOccurs="1" maxOccurs="1" type="dateTime"/>

    <element name="requestURL" minOccurs="1" maxOccurs="1" type="anyURI"/>

    <element name="record" minOccurs="0" maxOccurs="unbounded" 
             type="oai:recordType"/>

    <element name="resumptionToken" minOccurs="0" maxOccurs="1" type="string"/>

  </sequence>

  </complexType>



 <!-- define recordType -->

 <!-- a record has a header and a metadata part -->



 <complexType name="recordType">

  <sequence>

    <element name="header" minOccurs="1" maxOccurs="1" type="oai:headerType"/>

    <element name="metadata" minOccurs="0" maxOccurs="1" type="oai:metadataType"/>

    <element name="about" minOccurs="0" maxOccurs="1" type="oai:aboutType"/>

  </sequence>

  <attribute name="status" use="optional" type="oai:statusType"/>

 </complexType>



 <!-- define headerType -->

 <!-- a header has a unique identifier and a datestamp -->



 <complexType name="headerType">

  <sequence>

    <element name="identifier" minOccurs="1" maxOccurs="1" type="anyURI"/>

    <element name="datestamp" minOccurs="1" maxOccurs="1" type="date"/>

  </sequence>

 </complexType>



 <!-- define metadataType -->

 <!-- metadata must be expressed in XML that complies with another XML Schema -->

 <!-- metadata must be explicitly qualified in the response -->



 <complexType name="metadataType">

  <sequence>

   <any namespace="##other" processContents="lax"/>

  </sequence>

 </complexType>



<!-- define aboutType -->

<!-- data "about" the record must be expressed in XML -->

<!-- that is compliant with an XML Schema defined by a community -->



<complexType name="aboutType">

 <sequence>

  <any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="1"/>

 </sequence>

</complexType>



 <!-- define statusType -->
 <!-- a record can have a status of "deleted" . -->

<simpleType name="statusType">

  <restriction base="string">

   <enumeration value="deleted"/>

  </restriction>

</simpleType>


</schema>

This Schema is available at http://www.openarchives.org/OAI/1.1/OAI_ListRecords.xsd

Examples

Request

List the records in rfc1807 format added or modified since January 15, 1998 in the "hep" set of the "physics" set [URL shown without encoding for better readability].

http://an.oa.org/OAI-script?

       verb=ListRecords&from=1998-01-15&set=physics:hep&metadataPrefix=oai_rfc1807

Response

Three records are returned:

The first includes the rfc1807 metadata. This record also has an "about" part.
The second only has a header without the rfc1807 metadata container because the metadata for that record can not be expressed in rfc1807 format.
The third has a status="deleted" attribute (and therefore no metadata part).

<?xml version="1.0" encoding="UTF-8"?>

  <ListRecords 
      xmlns="http://www.openarchives.org/OAI/1.1/OAI_ListRecords"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_ListRecords         

                    http://www.openarchives.org/OAI/1.1/OAI_ListRecords.xsd">

    <responseDate>2001-06-01T19:20:30-04:00</responseDate> 

    <requestURL>http://an.oa.org/OAI-script?verb=ListRecords
                &amp;from=1998-01-15&amp;setSpec=physics%3Ahep
                &amp;metadataPrefix=oai_rfc1807</requestURL>

    <record>

      <header>

        <identifier>oai:arXiv:hep-th/9901001</identifier>

        <datestamp>1999-12-25</datestamp>

      </header>

      <metadata>

       <rfc1807 
         xmlns="http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1807.txt" 

         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

         xsi:schemaLocation=
             "http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1807.txt

              http://www.openarchives.org/OAI/1.1/rfc1807.xsd">
          <bib-version>v2</bib-version>
          <id>hep-th/9901001</id>

          <entry>January 1, 1999</entry>
          <title>Investigations of Radioactivity</title>

          <author>Ernest Rutherford</author>

          <date>March 30, 1999</date>

        </rfc1807>

      </metadata>

      <about>

       <dc xmlns="http://purl.org/dc/elements/1.1/" 

         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

         xsi:schemaLocation="http://purl.org/dc/elements/1.1/

                             http://www.openarchives.org/OAI/1.1/dc.xsd">

        <publisher>Los Alamos arXiv</publisher>

        <rights>Metadata may be used without restrictions as long as the oai 
         identifier remains attached to it.</rights>

       </dc>

      </about>

    </record>

    <record>

      <header>

        <identifier>oai:arXiv:hep-th/9901004</identifier>

        <datestamp>1999-12-26</datestamp>

      </header>

    </record>

    <record status="deleted">

      <header>

        <identifier>oai:arXiv:hep-th/9901007</identifier>

        <datestamp>1999-12-21</datestamp>

      </header>

    </record>

  </ListRecords>

4.6. ListSets

Summary and Usage Notes

This verb is used to retrieve the set structure in a repository.

Arguments

resumptionToken an EXCLUSIVE argument with a value that is the flow control token returned by a previous ListSets request that issued a partial response.

Exception Conditions

Repository contains no set hierarchy - The response will not contain any set containers.

Response Format

A XML schema for validating the response is as follows:

<schema xmlns="http://www.w3.org/2001/XMLSchema"

         xmlns:oai="http://www.openarchives.org/OAI/1.1/OAI_ListSets"

         targetNamespace="http://www.openarchives.org/OAI/1.1/OAI_ListSets"

         elementFormDefault="qualified"

         attributeFormDefault="unqualified">



  <annotation>

   <documentation>

    Schema to verify validity of responses to ListSets OAI-protocol request.

    This Schema validated at http://www.w3.org/2001/03/webdata/xsv on 2001-05-07

    with XSV XSV 1.189/1.95 of 2001/05/07 08:38:12

   </documentation>

  </annotation>



 <element name="ListSets" type="oai:ListSetsType"/>



 <!-- this response may contain an optional resumptionToken -->



 <complexType name="ListSetsType">

  <sequence>

    <element name="responseDate" minOccurs="1" maxOccurs="1" type="dateTime"/>

    <element name="requestURL" minOccurs="1" maxOccurs="1" type="anyURI"/>

    <element name="set" minOccurs="0" maxOccurs="unbounded" type="oai:setType"/>

    <element name="resumptionToken" minOccurs="0" maxOccurs="1" type="string"/>

  </sequence>

 </complexType>



 <!-- each set in the list consists of a setSpec and a pretty name -->



 <complexType name="setType">

  <sequence>

    <element name="setSpec" minOccurs="1" maxOccurs="1" type="oai:setSpecType"/>

    <element name="setName" minOccurs="1" maxOccurs="1" type="string"/>

  </sequence>

 </complexType>



 <simpleType name="setSpecType">

    <restriction base="string">

    <pattern value="([A-Za-z0-9])+(:[A-Za-z0-9]+)*"/>

    </restriction>

 </simpleType>



 </schema>

This Schema is available at http://www.openarchives.org/OAI/1.1/OAI_ListSets.xsd

Examples

Request

http://an.oa.org/OAI-script?

       verb=ListSets

Response

The following response indicates a set hierarchy with two top level sets - Oceanside and ValleyView - each with two sets within them.

<?xml version="1.0" encoding="UTF-8"?>

  <ListSets 
      xmlns="http://www.openarchives.org/OAI/1.1/OAI_ListSets"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_ListSets         

                    http://www.openarchives.org/OAI/1.1/OAI_ListSets.xsd">

    <responseDate>2001-06-01T19:20:30-04:00</responseDate> 

    <requestURL>http://an.oa.org/OAI-script?verb=ListSets</requestURL>

    <set>

      <setSpec>Oceanside</setSpec>

      <setName>Oceanside University of Nebraska</setName>

    </set>

    <set>

      <setSpec>Oceanside:CompEnt</setSpec>

      <setName>Department of Computational Entomology</setName>

    </set>

    <set>

      <setSpec>Oceanside:MetPhen</setSpec>

      <setName>Department of Metaphysical Phenomenology</setName>

    </set>

    <set>

      <setSpec>ValleyView</setSpec>

      <setName>Valley View University of Florida</setName>

    </set>

    <set>

      <setSpec>ValleyView:Fren</setSpec>

      <setName>Department of Frenetics</setName>

    </set>

    <set>

      <setSpec>ValleyView:Hist</setSpec>

      <setName>Department of Histrionics</setName>

    </set>

</ListSets>

Request

http://another.oa.org/OAI-script?

       verb=ListSets

Response

The response shows that the repository does not have a set hierarchy.

<?xml version="1.0" encoding="UTF-8"?>

  <ListSets 
      xmlns="http://www.openarchives.org/OAI/1.1/OAI_ListSets"
      xmlns:xsi="http://w

The Open Archives Initiative Protocol for Metadata Harvesting

Protocol Version 1.1 of 2001-07-02 Document Version 2001-06-20 http://www.openarchives.org/OAI/openarchivesprotocol.htm Previous version: Protocol Version 1.0 of 2001-01-21 Instructions for migrating from Version 1.0 to 1.1

1. Introduction

2. Definitions and Concepts

2.1 Repository

2.2 Record

2.3 Unique Identifier

2.4 Datestamp

2.5 Set

3.0 Protocol Features

3.1 HTTP embedding of OAI requests

3.1.1 HTTP Request Format

3.1.1.1 Encoding an OAI protocol request in a URL for an HTTP GET

3.1.1.2 Encoding an OAI protocol request in an HTTP POST

3.1.1.3 Encoding of special characters in keyword arguments of OAI protocol requests

3.1.2 HTTP Response Format

3.1.2.1 Content-Type

3.1.2.2 Status-Code

3.2 Dates and Times

3.3 Metadata Prefix and Metadata Schema

3.4 Flow Control

4. Protocol Requests and Responses

4.1. GetRecord

Summary and Usage Notes

Arguments

Exception Conditions

Response Format

Examples

Request

Response

Request

Response

Request

Response

4.2. Identify

Summary and Usage Notes

Arguments

Exception Conditions

Response Format

Examples

Request

Response

4.3. ListIdentifiers

Summary and Usage Notes

Arguments

Exception Conditions

Response Format

Examples

Request

Response

Request

Response

Request

Response

4.4. ListMetadataFormats

Summary and Usage Notes

Arguments

Exception Conditions

Response Format

Examples

Request

Response

Request

Response

Request

Response

4.5. ListRecords

Summary and Usage Notes

Arguments

Exception Conditions

Response Format

Examples

Request

Response

4.6. ListSets

Summary and Usage Notes

Arguments

Exception Conditions

Response Format

Examples

Protocol Version 1.1 of 2001-07-02
Document Version 2001-06-20
http://www.openarchives.org/OAI/openarchivesprotocol.htm

Previous version: Protocol Version 1.0 of 2001-01-21
Instructions for migrating from Version 1.0 to 1.1