The Open Archives Initiative Protocol for Metadata Harvesting (referred to as the OAI-PMH in the remainder of this document) provides an application-independent interoperability framework based on metadata harvesting. There are two classes of participants in the OAI-PMH framework:

In this document the key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" in bold face are to be interpreted as described in RFC 2119. An implementation is not conformant if it fails to satisfy one or more of the "must" or "required" level requirements for the protocols it implements.

This document refers in several places to "community-specific" practices to which individual protocol implementations may conform. These practices are described in an accompanying Implementation Guidelines document.

2. Definitions and Concepts

2.1 Repository

A repository is a network accessible server to which OAI-PMH requests can be submitted. The OAI-PMH provides access to metadata from OAI-conformant repositories. For flexibility in repository configuration, the OAI-PMH defines three distinct entities related to the metadata made accessible by OAI-PMH:

All uses of the term repository in the remainder of this document should be interpreted as an OAI-PMH conformant repository.

2.2 Harvester

A harvester is a client application that issues OAI-PMH requests. Typically a harvester is run by a service provider as a means of collecting metadata from repositories.

2.3 Record

2.3.1 Deleted Records

The protocol supports the optional notion of a deleted record. If a repository supports the notion of deleted records, it must be used as follows:

When returning a harvested record or identifier of a record, the ListRecords and ListIdentifiers 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 request.

2.4 Unique Identifier

A unique identifier is a key in an OAI-PMH request for extracting metadata from an item. Items may contain metadata in multiple formats. The unique identifier maps to the item and all possible metadata formats disseminated in records from a single item share the same unique identifier. Each record disseminated by a GetRecord or ListRecords request is identified by the combination of this unique identifier and a metadataPrefix, which identifies the metadata format.

The format of the unique identifier must correspond to that of the URI (Uniform Resource Identifier) syntax. Individual communities may develop community-specific URI schemes for coordinated use across repositories.

Note that the identifier described here is not that of a resource. The nature of a resource identifier is outside the scope of the OAI-PMH.

To facilitate access the resource associated with harvested metadata, repositories should 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 resource. The mandatory Dublin Core format provides the identifier element that should be used for this purpose.

2.5 Datestamp

A datestamp is a date and time that is used for selective harvesting on the basis of the instant that changes to items in the repository occur. Every record returned by the GetRecord and ListRecords requests contains its respective datestamp in the header. A repository must change a datestamp to indicate creation or modification of an item. Datestamps are used as values of optional arguments, until and from, to the ListRecords and ListIdentifiers requests to specify selective harvesting within the range of those arguments. The value of a datestamp must comply to the specifications for UTCdatetime in this document.

2.6 Set

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

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

An item may be organized in one set, several sets, or no sets at all. A harvester should not assume that harvesting every set in a repository will retrieve all metadata 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 institution:florida.

The actual meaning of a set or of the arrangement of sets in a repository is not defined in the protocol. It is expected that individual communities may formulate well-defined set configurations with perhaps a controlled vocabulary for set names, and may even develop mechanisms for exposing these to harvesters. For example, a group of cooperating e-print archives in a specific discipline may agree on sets that arrange metadata in their repositories based on a controlled subject classification.

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. Each member of this list must include a setName and may include a setDescription. ListRecords and ListIdentifiers requests may include an optional set argument, the value of which is a setSpec, to specify the target set for selective harvesting. In the previous example of a set hierarchy, the setSpec institution:nebraska could be used in a request to return only those records that are disseminated from items organized in the set represented by this setSpec. Four issues should be noted here:

3.0 Protocol Features

3.1 HTTP embedding of OAI-PMH requests

3.1.1 HTTP Request Format

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 must be separated by ampersands [&]. Each OAI-PMH request must have at least one key=value pair that specifies the OAI-PMH request issued by the harvester:

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

3.1.1.1 Encoding an OAI-PMH request in a URL for an HTTP GET

However, since special characters in URIs must be encoded, the correct 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-PMH request in an HTTP POST

3.1.1.3 Encoding of special characters in keyword arguments of OAI-PMH requests

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

Datestamps appear in the headers of records that are returned in response to GetRecord and ListRecords requests. These datestamps are encoded using ISO8601 and are expressed in UTC; they must be expressed in the finest granularity supported by the repository.

Each protocol response includes a responseDate element, which must be the time and date of the response in UTC. This is encoded using the "Complete date plus hours, minutes, and seconds" or the "Complete date plus hours, minutes, and seconds and a decimal fraction of a second" variants of ISO8601. These formats are respectively YYYY-MM-DDThh:mm:ssZ and YYYY-MM-DDThh:mm:ss.sZ.

A resumptionToken in a protocol reply takes an optional argument expirationDate, which is expressed in UTC. This is encoded using the "Complete date plus hours, minutes, and seconds" or the "Complete date plus hours, minutes, and seconds and a decimal fraction of a second" variants of ISO8601. These formats are respectively YYYY-MM-DDThh:mm:ssZ and YYYY-MM-DDThh:mm:ss.sZ.

3.3 metadataPrefix and Metadata Schema

Each metadata format disseminated by a repository is identified within OAI-PMH requests by a metadataPrefix. Repositories express the use of a common metadata format by referencing a common metadata schema:

The metadataPrefix must be a non-space embedded string consisting of alphanumeric characters or the underscore [_] character.
The metadata schema is an XML schema referenced via a URL to test validity of XML records. 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 request. For each metadata format supported, the response to the ListMetadataFormats requests must contain the metadataPrefix of the format and the URL of the metadata schema for the metadata format. Optionally, this response may also contain the XML namespace URI that globally identifies the metadata format.

metadataPrefixes are used in the ListRecords and GetRecord requests, to request records that include metadata in the format identified by the metadataPrefix.

The metadata in each record returned by ListRecords and GetRecord must comply with 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 must match the URL of the metadata schema for the metadataPrefix included as an argument to the ListRecords or GetRecord request (the mapping from metadataPrefix to metadata schema is defined by the repository's response to the ListMetadataFormats request).

For purposes of interoperability, repositories must disseminate Dublin Core, without any qualification. Therefore, the protocol reserves the metadataPrefix 'oai_dc', and the URL of a metadata schema for unqualified Dublin Core, which is http://www.openarchives.org/OAI/2.0/oai_dc.xsd.

Communities should adopt guidelines for sharing of metadataPrefixes and/or metadata schema. Such guidelines are outside of the scope of the OAI-PMH. The accompanying Implementation Guidelines document provides some sample XML Schema and instance documents for common metadata formats such as MARC and RFC 1807.

3.4 Flow Control

A number of OAI-PMH 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 requests and responses. This partitioning is accomplished as follows:

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

Details of flow control and the resumptionToken are as follows:

The only defined use of resumptionToken is as follows:
- a repository includes a resumptionToken element as part of each response that includes an incomplete list;
- in order to retrieve the next portion of the complete list, the next request uses the value of that resumptionToken element as the value of the resumptionToken argument of the request;
- the response containing the incomplete list that completes the list includes an empty resumptionToken element;
All other uses of resumptionToken by a harvester are illegal and will produce an error.
In all cases when a resumptionToken is issued, the incomplete list must consist of complete entities; e.g., all individual records returned in an incomplete record list from a ListRecords request must be intact.
The format of the resumptionToken is not defined by the OAI-PMH and should be considered opaque by the harvester.
The protocol does not define the semantics of incompleteness. Therefore, a harvester should not assume that the members in an incomplete list conform to some selection criteria (e.g., date ordering).
Before including a resumptionToken in the URL of a subsequent request, a harvester must encode any special characters in it.

The following optional attributes may be included as part of the resumptionToken element along with the resumptionToken itself:

resumeAfter -- an indication of the number of seconds that the harvester should wait before issuing the follow-on request, expressed as a positive integer;
expirationDate -- a UTCdatetime indicating when the resumptionToken ceases to be valid.
completeListSize -- an integer indicating the cardinality of the complete list (i.e., the sum of the cardinalities of the incomplete lists).
cursor -- a count of the number of elements of the complete list thus far returned (i.e. cursor starts at 0).

The following example is a series of ListRecords requests where the complete list consists of 175 records and the repository only returns 100 records per response.

The harvester issues a ListRecords request.
The repository responds with an incomplete list of 100 records. The repository marks this list as incomplete by including in the response a non-empty resumptionToken element, with two attributes: a completeListSize of 175, and a cursor of 0.
The harvester issues a subsequent ListRecords request that includes the resumptionToken that it received in the previous response.
The respository responds with an incomplete list of 75 records. The repository marks this list as the final incomplete list by including in the response an empty resumptionToken element with two attributes: a completeListSize of 175, and a cursor of 100.

This flow control mechanism, in combination with HTTP transport layer facilities, provides some basic tools with which a repository can enforce an acceptable use policy for its harvesting interface. Communities implementing the OAI-PMH 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-PMH.

3.5 Error Conditions

Repositories must indicate OAI-PMH errors, distinguished from HTTP status-codes, by including one or more error elements in the response. While one error element is sufficient to indicate the presence of the error condition, repositories should report all errors that arise from processing the request. Each error element must have a code attribute that must be from the following table. Each error element may also have a free text string value to provide information about the error that is useful to a human reader. These strings are not defined by OAI-PMH.

Error Codes Description Applicable Verbs

badArgument The request includes illegal arguments or is missing required arguments. all verbs

badGranularity
The values of the from and until arguments are illegal or specify a finer granularity than is supported by the repository. ListIdentifiers
ListRecords

badResumptionToken The value of the resumptionToken argument is invalid or expired. ListIdentifers
ListRecords
ListSets

badVerb
Value of the verb argument is not a legal OAI-PMH verb or the verb argument is missing. The badVerb error is contained within an Identify verb response. N/A

cannotDisseminateFormat
The value of the metadataPrefix argument is not supported by the repository. GetRecord
ListIdentifiers
ListRecords

idDoesNotExist
The value of the identifier argument is unknown or illegal in this repository. GetRecord
ListMetadataFormats

noRecordsMatch
The combination of the values of the from, until, set and metadataPrefix arguments results in an empty list. ListIdentifiers
ListRecords

noSetHierarchy
The repository does not support sets. ListSets

The following example demonstrates error handling in the case of an illegal verb argument. Note that the response is formatted according to the Identity verb, including the relevant error code.

Request

http://arXiv.org/oai2?
       verb=nastyVerb

Response

<?xml version="1.0" encoding="UTF-8"?>
<Identify xmlns="http://www.openarchives.org/OAI/2.0/"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/
             http://www.openarchives.org/OAI/2.0/OAI_Identify.xsd">
  <responseDate>2002-05-01T09:18:29Z</responseDate>
  <requestURL>http://arXiv.org/oai2?verb=nastyVerb</requestURL>
  <error code="badVerb">Illegal OAI verb</error>
  <repositoryName>arXiv</repositoryName>
  <baseURL>http://arXiv.org/oai2</baseURL>
  <protocolVersion>2.0</protocolVersion>
  <adminEmail>www-admin@arXiv.org</adminEmail>
  <compression>gzip</compression>
</Identify>

The following example demonstrates error handling in the case of a ListSets request to a repository that does not handle sets.

Request

http://arXiv.org/oai2?
       verb=ListSets

Response

<?xml version="1.0" encoding="UTF-8"?>
<ListSets xmlns="http://www.openarchives.org/OAI/2.0/"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/
          http://www.openarchives.org/OAI/2.0/OAI_ListSets.xsd">
  <responseDate>2002-05-01T09:18:29Z</responseDate>
  <requestURL>http://arXiv.org/oai2?verb=ListSets</requestURL>
  <error code="noSetHierarchy">This repository does not support sets</error>
</ListSets>

4. Protocol Requests and Responses

This section lists the requests, or verbs, defined in the OAI-PMH. The documentation for each request is organized as follows:

A section title corresponding to the token used to specify the request as the required verb argument to an HTTP 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, as described in HTTP Request Format).
- optional, the argument may be included with the request.
- exclusive, the argument may be included with request, but must be the only argument (in addition to the verb argument).
The format of the response defined by an XML schema.
Error conditions specific to the protocol request.
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 metadata record 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 is the key for retrieving the requested record from the repository.
metadataPrefix a required argument that specifies the metadataPrefix of the format that should be included in the metadata part of the returned record. The metadata formats supported by a repository and for a particular record can be retrieved using the ListMetadataFormats request.

Error Conditions

badArgument - The request includes illegal arguments or is missing required arguments.
cannotDisseminateFormat - The value of the metadataPrefix argument is not supported by the repository.
idDoestNotExist - The value of the identifier argument is unknown or illegal in this repository.

Response Format

A XML schema for validating the response is as follows:

<schema targetNamespace="http://www.openarchives.org/OAI/2.0/" 
        xmlns="http://www.w3.org/2001/XMLSchema" 
        xmlns:oai="http://www.openarchives.org/OAI/2.0/" 
        elementFormDefault="qualified" attributeFormDefault="unqualified">

  <annotation>
    <documentation>
     Schema to verify validity of responses to GetRecord OAI-protocol request.
     This Schema validated with XML Spy version 4.2 on 2002-03-01</documentation>
  </annotation>

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

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

  <complexType name="GetRecordType">
    <sequence>
      <element name="responseDate" type="oai:UTCdatetimeType"/>
      <element name="requestURL" type="anyURI"/>
      <element name="error" type="oai:GetRecordErrorType" minOccurs="0" maxOccurs="unbounded"/>
      <element name="record" type="oai:recordType" minOccurs="0" maxOccurs="1"/>
     </sequence>
   </complexType>

  <simpleType name="UTCdatetimeType">
    <union memberTypes="date dateTime"/>
  </simpleType>

  <!-- valid error codes for GetRecord -->
	
  <complexType name="GetRecordErrorType">
    <simpleContent>
      <extension base="string">
        <attribute name="code" type="oai:GetRecordErrorcodeType" use="required"/>
      </extension>
    </simpleContent>
  </complexType>
	
  <simpleType name="GetRecordErrorcodeType">
    <restriction base="string">
      <enumeration value="cannotDisseminateFormat"/>
      <enumeration value="idDoesNotExist"/>
      <enumeration value="badArgument"/>
    </restriction>
  </simpleType>
	
  <!-- define recordType -->
  <!-- a record has a header, a metadata part, and an optional about container -->
	
  <complexType name="recordType">
    <sequence>
      <element name="header" type="oai:headerType"/>
      <element name="metadata" type="oai:metadataType" minOccurs="0"/>
      <element name="about" type="oai:aboutType" minOccurs="0" maxOccurs="unbounded"/>
    </sequence>
      <attribute name="status" type="oai:statusType" use="optional"/>
  </complexType>
	
  <!-- define headerType -->
  <!-- a header has a unique identifier, a datestamp, 
       and setSpec(s) in case the record belongs to set(s),  -->

  <complexType name="headerType">
    <sequence>
      <element name="identifier" type="anyURI"/>
      <element name="datestamp" type="oai:oaiDateTimeType"/>
      <element name="setSpec" type="oai:setSpecType" minOccurs="0" maxOccurs="unbounded"/>
    </sequence>
  </complexType>
  
  <simpleType name="oaiDateTimeType">
    <union memberTypes="date dateTime"/>
  </simpleType>

  <simpleType name="setSpecType">
    <restriction base="string">
      <pattern value="([A-Za-z0-9_!\-\.\*])+(:[A-Za-z0-9A-Za-z0-9_!\-\.\*]+)*"/>
    </restriction>
  </simpleType>

  <!-- 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"/>
    </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/2.0/OAI_GetRecord.xsd

Examples

Request

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

http://arXiv.org/oai2?
       verb=GetRecord&identifier=oai:arXiv:cs/0112017&metadataPrefix=oai_dc

Response

<?xml version="1.0" encoding="UTF-8"?> 
<GetRecord xmlns="http://www.openarchives.org/OAI/2.0/" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ 
           http://www.openarchives.org/OAI/2.0/OAI_GetRecord.xsd"> 
  <responseDate>2002-02-08T08:55:46Z</responseDate>
  <requestURL>http://arXiv.org/oai2?verb=GetRecord
              &amp;identifier=oai%3AarXiv%3Acs%2F0112017
              &amp;metadataPrefix=oai_dc</requestURL> 
  <record> 
    <header>
      <identifier>oai:arXiv:cs/0112017</identifier> 
      <datestamp>2001-12-14</datestamp>
      <setSpec>cs</setSpec> 
      <setSpec>math</setSpec>
    </header>
    <metadata>
      <oaidc:oai_dc xmlns:oaidc="http://www.openarchives.org/oaidc/" 
                    xmlns="http://purl.org/dc/elements/1.1/" 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:schemaLocation="http://www.openarchives.org/oaidc/ 
                    http://www.openarchives.org/OAI/2.0/oai_dc.xsd">
        <title>Using Structural Metadata to Localize Experience of Digital Content</title> 
        <creator>Dushay, Naomi</creator>
        <subject>Digital Libraries</subject> 
        <description>With the increasing technical sophistication of both information 
         consumers and providers, there is increasing demand for more meaningful experiences 
         of digital information. We present a framework that separates digital object experience, 
         or rendering, from digital object storage and manipulation, so the rendering can 
         be tailored to particular communities of users.</description> 
        <description>Comment: 23 pages including 2 appendices, 8 figures</description> 
        <date>2001-12-14</date>
      </oaidc:oai_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. It does have an error element with a code attribute that has the value idDoesNotExist. [URL shown without encoding for better readability].

http://arXiv.org/oai2?
       verb=GetRecord&identifier=oai:arXiv:quant-ph/02131001&metadataPrefix=oai_dc

Response

<?xml version="1.0" encoding="UTF-8"?> 
<GetRecord xmlns="http://www.openarchives.org/OAI/2.0/" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ 
           http://www.openarchives.org/OAI/2.0/OAI_GetRecord.xsd"> 
  <responseDate>2002-02-08T08:55:46Z</responseDate>
  <requestURL>http://arXiv.org/oai2?verb=GetRecord
              &amp;identifier=oai%3AarXiv%3Aquant-ph%2F0213001
              &amp;metadataPrefix=oai_dc</requestURL> 
  <error code="idDoesNotExist">No matching identifier in arXiv</error>
</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 contains no record. It does contain an error element with a code attribute that has the value cannotDisseminateFormat. [URL shown without encoding for better readability].

http://arXiv.org/oai2?
       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/2.0/" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ 
           http://www.openarchives.org/OAI/2.0/OAI_GetRecord.xsd"> 
  <responseDate>2002-02-08T08:55:46Z</responseDate>
  <requestURL>http://arXiv.org/oai1?verb=GetRecord
              &amp;identifier=oai%3AarXiv%3Aquant-ph%2F9901001
              &amp;metadataPrefix=oai_marc</requestURL> 
  <error code="cannotDisseminateFormat"/>
</GetRecord>

4.2. Identify

Summary and Usage Notes

This verb is used to retrieve information about a repository. Some of the information returned is required as part of the OAI-PMH. Repositories may also employ the Identify verb to return additional descriptive information.

Arguments

None

Error Conditions

badArgument - The request includes illegal arguments or is missing required arguments.
badVerb - Value of the verb argument is not a legal OAI-PMH verb or the verb argument is missing. (Note: this is the only case in which the nature of an OAI-PMH response does not match the argument to the verb argument.)

Response Format

A XML schema for validating the response is as follows:

<schema targetNamespace="http://www.openarchives.org/OAI/2.0/" 
        xmlns="http://www.w3.org/2001/XMLSchema" 
        xmlns:oai="http://www.openarchives.org/OAI/2.0/" 
        elementFormDefault="qualified" attributeFormDefault="unqualified">

  <annotation>
    <documentation>
     Schema to verify validity of responses to Identify OAI-protocol request.
     This Schema validated with XML Spy version 4.2 on 2002-03-01</documentation>
  </annotation>

  <element name="Identify" type="oai:IdentifyType"/>
  
  <!-- response to Identify-request -->

  <complexType name="IdentifyType">
    <sequence>
      <element name="responseDate" type="oai:UTCdatetimeType"/>
      <element name="requestURL" type="anyURI"/>
      <element name="error" type="oai:IdentifyErrorType" minOccurs="0" maxOccurs="unbounded"/>
      <element name="repositoryName" type="string"/>
      <element name="baseURL" type="anyURI"/>
      <element name="protocolVersion" type="string"/>
      <element name="adminEmail" type="oai:emailType"/>
      <element name="granularity" type="oai:granularityType" minOccurs="0" maxOccurs="1"/>
      <element name="compression" type="oai:compressionType" minOccurs="0" maxOccurs="unbounded"/>
      <element name="description" type="oai:descriptionType" minOccurs="0" maxOccurs="unbounded"/>
    </sequence>
  </complexType>

  <simpleType name="UTCdatetimeType">
    <union memberTypes="date dateTime"/>
  </simpleType>

<!-- valid error codes for Identify -->

  <complexType name="IdentifyErrorType">
    <simpleContent>
      <extension base="string">
        <attribute name="code" type="oai:IdentifyErrorcodeType" use="required"/>
      </extension>
    </simpleContent>
  </complexType>

  <simpleType name="IdentifyErrorcodeType">
    <restriction base="string">
      <enumeration value="badVerb"/>
      <enumeration value="badArgument"/>
    </restriction>
  </simpleType>

  <simpleType name="emailType">
    <simpleContent>
      <restriction base="anyURI">
        <pattern value="mailto:\S+@(\S\.)+\S+"/>
      </restriction>
    </simpleContent>
  </simpleType>

  <complexType name="descriptionType">
    <sequence>
      <any namespace="##other" processContents="lax"/>
    </sequence>
  </complexType>

  <simpleType name="granularityType">
    <restriction base="string">
      <enumeration value="YYYY-MM-DD"/>
      <enumeration value="YYYY-MM-DDThh:mmZ"/>
      <enumeration value="YYYY-MM-DDThh:mm:ssZ"/>
      <enumeration value="YYYY-MM-DDThh:mm:ss.sZ"/>
    </restriction>
  </simpleType>

  <!-- compression types as listed in 3.5 of RFC2616 - 
       http://www.ietf.org/rfc/rfc2616.txt -->

  <simpleType name="compressionType">
    <restriction base="string">
      <enumeration value="gzip"/>
      <enumeration value="compress"/>
      <enumeration value="deflate"/>
    </restriction>
  </simpleType>

</schema>

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

Examples

Request

http://memory.loc.gov/cgi-bin/oai?
       verb=Identify

Response

The response must include one instance of the following elements:

repositoryName: a human readable name for the repository;
baseURL: the base URL of the repository;
protocolVersion: the version of the OAI-PMH supported by the repository;
adminEmail: the e-mail address of the administrator of the repository, formatted as a mailto URI.

The response may include one instance of the following optional element:

granularity: the finest harvesting granularity supported by the repository. The legitimate values are YYYY-MM-DD ; YYYY-MM-DDThh:mmZ ; YYYY-MM-DDThh:mm:ssZ and YYYY-MM-DDThh:mm:ss.sZ with meanings as defined in ISO8601. The granularity YYYY-MM-DDThh:mm:ssZ is used as shorthand for both YYYY-MM-DDThh:mm:ssZ and YYYY-MM-DDThh:mm:ss.sZ formats.

The response may include multiple instances of the following optional elements:

compression: a compression encoding supported by the repository. The allowed values are those defined for the Content-Encoding header in Section 14.11 of RFC 2616 describing HTTP 1/1 . A compression element should not be included for the identity encoding, which is implied.
description: an extensible mechanism for communities to describe their repositories. For example, the description container could be used to include collection-level metadata in the response to the Identify request. Implementation Guidelines are available to give directions with this respect. Each description container must be accompanied by the URL of an XML schema describing the structure of the description 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, provided in the accompanying Implementation Guidelines document, 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, provided in the accompanying Implementation Guidelines document, 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/2.0/" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ 
          http://www.openarchives.org/OAI/2.0/OAI_Identify.xsd">
  <responseDate>2002-02-08T12:00:01Z</responseDate>
  <requestURL>http://memory.loc.gov/cgi-bin/oai?verb=Identify</requestURL>
    <repositoryName>Library of Congress Open Archive Initiative Repository 1</repositoryName>
    <baseURL>http://memory.loc.gov/cgi-bin/oai</baseURL>
    <protocolVersion>2.0</protocolVersion>
    <adminEmail>mailto:dwoo@loc.gov</adminEmail>
    <granularity>YYYY-MM-DDThh:mmZ</granularity>
    <compression>deflate</compression>
    <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>lcoa1</repositoryIdentifier>
        <delimiter>:</delimiter>
        <sampleIdentifier>oai:lcoa1:loc.music/musdi.002</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://memory.loc.gov/ammem/oamh/lcoa1_content.html</URL>
          <text>Selected collections from American Memory at the Library of Congress</text>
        </content>
        <metadataPolicy/>
        <dataPolicy/>
      </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 returned based on their membership in a specific set in the repository, their availability in a specific metadata format, or based on their modification, creation, or deletion within a specific date range.

Arguments

until an optional argument with a UTCdatetime value, which specifies that only the unique identifiers of records with a datestamp older than or equal to the specified date/time should be returned.
from an optional argument with a UTCdatetime value, which specifies that only the unique identifiers of records with a datestamp that is more recent than or equal to the specified date/time should be returned.
metadataPrefix an optional argument, which specifies that only the unique identifiers of records available in the metadata format matching the supplied metadataPrefix should be returned. The metadata formats supported by a repository and for a particular record can be retrieved using the ListMetadataFormats request.
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 an incomplete list.

Error Conditions

badArgument - The request includes illegal arguments or is missing required arguments.
badGranularity - The values of the from and until arguments are illegal or specify a finer granularity than is supported by the repository.
badResumptionToken - The value of the resumptionToken argument is invalid or expired.
cannotDisseminateFormat - The value of the metadataPrefix argument is not supported by the repository.
noRecordsMatch - The combination of the values of the from, until, and set arguments results in an empty list.

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/2.0/"
        targetNamespace="http://www.openarchives.org/OAI/2.0/"
        elementFormDefault="qualified"
        attributeFormDefault="unqualified">

  <annotation>
    <documentation>
     Schema to verify validity of responses to ListIdentifiers OAI-protocol request.
     This Schema validated with XML Spy version 4.2 on 2002-03-01</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="oai:UTCdatetimeType"/>
      <element name="requestURL" minOccurs="1" maxOccurs="1" type="anyURI"/>
       <element name="error" minOccurs="0" maxOccurs="unbounded" type="oai:ListIdentifiersErrorType"/>
      <element ref="oai:identifier" minOccurs="0" maxOccurs="unbounded"/>
      <element ref="oai:resumptionToken" minOccurs="0" maxOccurs="1" />
    </sequence>
  </complexType>

  <simpleType name="UTCdatetimeType">
    <union memberTypes="date dateTime"/>
  </simpleType>

<!-- valid error codes for ListIdentifiers -->
  
  <complexType name="ListIdentifiersErrorType">
    <simpleContent>
      <extension base="string">
        <attribute name="code" type="oai:ListIdentifiersErrorcodeType" use="required"/>
      </extension>
    </simpleContent>
  </complexType>
	
  <simpleType name="ListIdentifiersErrorcodeType">
    <restriction base="string">
      <enumeration value="badArgument"/>
      <enumeration value="noRecordsMatch"/>
      <enumeration value="badGranularity"/>
      <enumeration value="badResumptionToken"/>
      <enumeration value="cannotDisseminateFormat"/>
    </restriction>
  </simpleType>

  <!-- define identifier -->

  <element name="identifier">
    <complexType>
      <simpleContent>
        <extension base="anyURI">
          <attribute name="status" use="optional" type="oai:statusType"/>
        </extension>
      </simpleContent>
    </complexType>
  </element>

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

  <simpleType name="statusType">
    <restriction base="string">
      <enumeration value="deleted"/>
    </restriction>
  </simpleType>

  <!-- define resumptionToken - with 4 optional attributes -->

  <element name="resumptionToken">
    <complexType>
      <attribute name="resumeAfter" type="positiveInteger"/>
      <attribute name="expirationDate" type="oai:UTCdatetimeType" use="optional"/>
      <attribute name="completeListSize" type="positiveInteger" use="optional"/>
      <attribute name="cursor" type="nonNegativeInteger" use="optional"/>
    </complexType>
  </element>

</schema>

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

Examples

Request

List the unique identifiers of records added or modified since January 15, 1998 in the hep subset 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 resumptionToken (non-empty, value xxx45abttyz) has been returned, indicating that the list of identifiers is incomplete and that one or more subsequent requests will need to be issued to retrieve a complete list. In the example, the resumptionToken comes with all of the 4 optional attributes: expirationDate indicates that the resumptionToken will become unusable after 11:20 PM UTC on June 1st 2002; resumeAfter indicates that the harvester should issue the next OAI-PMH request using the given value of resumptionToken after 120 seconds; completeListSize indicates that the complete list consists of 6 identifiers; the zero-value for cursor indicates that no identifiers have been returned previous to this reply.

<?xml version="1.0" encoding="UTF-8"?>
<ListIdentifiers 
      xmlns="http://www.openarchives.org/OAI/2.0/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/        
      http://www.openarchives.org/OAI/2.0/OAI_ListIdentifiers.xsd">
  <responseDate>2002-06-01T19:20:30Z</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 expirationDate="2002-06-01T23:20:00Z" resumeAfter="120" 
     completeListSize="6" cursor="0">xxx45abttyz</resumptionToken>
</ListIdentifiers>

Request

Issue a subsequent request to the one issued above. The single resumptionToken argument has the value returned in the previous response. [URL shown without encoding for better readability].

http://an.oa.org/OAI-script?
       verb=ListIdentifiers&resumptionToken=xxx45abttyz

Response

Two more identifiers are returned. The resumptionToken element at the end of the list has no value, indicating that the list is now complete. The value of the completeListSize attribute remains 6, while the value of the cursor attribute has changed to 4, indicating that a previous reply has (or previous replies have) already delivered 4 identifiers.

<?xml version="1.0" encoding="UTF-8"?>
<ListIdentifiers 
      xmlns="http://www.openarchives.org/OAI/2.0/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/        
      http://www.openarchives.org/OAI/2.0/OAI_ListIdentifiers.xsd">
  <responseDate>2002-06-01T19:30:00Z</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>
  <resumptionToken completeListSize="6" cursor="4"/>
</ListIdentifiers>

Request

List the unique identifiers of records added or modified on January 1, 2001 in the set Perseus:collection:PersInfo, from which metadata in the olac format is available. There are no matches for this request, hence, the response contains an error tag and does not contain any identifier tags [URL shown without encoding for better readability].

http://www.perseus.tufts.edu/cgi-bin/pdataprov?
       verb=ListIdentifiers&metadataPrefix=olac&from=2001-01-01&until=2001-01-01&set=Perseus:collection:PersInfo

Response

<?xml version="1.0" encoding="UTF-8"?>
<ListIdentifiers xmlns="http://www.openarchives.org/OAI/2.0/" 
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                 xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ 
                 http://www.openarchives.org/OAI/2.0/OAI_ListIdentifiers.xsd">
  <responseDate>2002-02-08T14:27:19Z</responseDate>
  <requestURL>http://www.perseus.tufts.edu/cgi-bin/pdataprov?verb=ListIdentifiers
              &amp;metadataPrefix=olac&amp;from=2001-01-01&amp;until=2001-01-01
              &amp;set=Perseus%3Acollection%3APersInfo</requestURL>
  <error code="noRecordsMatch"/>
</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 from all items.

Error Conditions

badArgument - The request includes illegal arguments or is missing required arguments.
idDoesNotExist - The value of the identifier argument is unknown or illegal in this repository.

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/2.0/"
        targetNamespace="http://www.openarchives.org/OAI/2.0/"
        elementFormDefault="qualified" attributeFormDefault="unqualified">

  <annotation>
    <documentation>
     Schema to verify validity of responses to ListMetadataFormats OAI-protocol request.
     This Schema validated with XML Spy version 4.2 on 2002-03-01</documentation>
  </annotation>

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

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

  <complexType name="ListMetadataType">
    <sequence>
      <element name="responseDate" minOccurs="1" maxOccurs="1" type="oai:UTCdatetimeType"/>
      <element name="requestURL" minOccurs="1" maxOccurs="1" type="anyURI"/>
      <element name="error" type="oai:ListMetadataFormatsErrorType" minOccurs="0" maxOccurs="unbounded"/>
      <element name="metadataFormat" minOccurs="0" maxOccurs="unbounded" type="oai:metadataFormatType"/>
    </sequence>
  </complexType>

  <simpleType name="UTCdatetimeType">
    <union memberTypes="date dateTime"/>
  </simpleType>

<!-- valid error codes for ListMetadataFormats -->

  <complexType name="ListMetadataFormatsErrorType">
    <simpleContent>
      <extension base="string">
        <attribute name="code" type="oai:ListMetadataFormatsErrorcodeType" use="required"/>
      </extension>
   </simpleContent>
  </complexType>

  <simpleType name="ListMetadataFormatsErrorcodeType">
    <restriction base="string">
      <enumeration value="idDoesNotExist"/>
      <enumeration value="badArgument"/>
    </restriction>
  </simpleType>

  <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/2.0/OAI_ListMetadataFormats.xsd

Examples

Request

List the metadata formats that can be disseminated from the repository http://www.perseus.tufts.edu/cgi-bin/pdataprov for the unique identifier oai:perseus:Perseus:text:1999.02.0119 [URL shown without encoding for better readability].

http://www.perseus.tufts.edu/cgi-bin/pdataprov?
       verb=ListMetadataFormats&identifier=oai:perseus:Perseus:text:1999.02.0119

Response

The response shows that 3 metadata formats are supported for the given identifier: oai_dc, olac and perseus. For each of the formats, the location of an XML Schema describing the format is given.

<?xml version="1.0" encoding="UTF-8"?>
<ListMetadataFormats xmlns="http://www.openarchives.org/OAI/2.0/" 
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ 
                     http://www.openarchives.org/OAI/2.0/OAI_ListMetadataFormats.xsd">
  <responseDate>2002-06-18T15:44:33Z</responseDate>
  <requestURL>http://www.perseus.tufts.edu/cgi-bin/pdataprov?verb=ListMetadataFormats
              &amp;identifier=oai%3Aperseus%3APerseus%3Atext%3A1999.02.0119</requestURL>
  <metadataFormat>
    <metadataPrefix>oai_dc</metadataPrefix>
    <schema>http://www.openarchives.org/OAI/2.0/oai_dc.xsd</schema>
  </metadataFormat>
  <metadataFormat>
    <metadataPrefix>olac</metadataPrefix>
    <schema>http://www.language-archives.org/OLAC/olac-0.2.xsd</schema>
  </metadataFormat>
  <metadataFormat>
    <metadataPrefix>perseus</metadataPrefix>
    <schema>http://www.perseus.tufts.edu/persmeta.xsd</schema>
  </metadataFormat>
</ListMetadataFormats>

Request

List the metadata formats that can be disseminated from the repository http://memory.loc.gov/cgi-bin/oai.

http://memory.loc.gov/cgi-bin/oai?
       verb=ListMetadataFormats

Response

The response shows that the repository supports 2 metadata formats: oai_dc, and oai_marc. For each of the formats, the location of an XML Schema describing the format is given. The support of these formats at the repository-level does not imply support of each format for each identifier of the repository.

<?xml version="1.0" encoding="UTF-8"?>
<ListMetadataFormats xmlns="http://www.openarchives.org/OAI/2.0/" 
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ 
                     http://www.openarchives.org/OAI/2.0/OAI_ListMetadataFormats.xsd">
  <responseDate>2002-06-08T15:19:13Z</responseDate>
  <requestURL>http://memory.loc.gov/cgi-bin/oai?verb=ListMetadataFormats</requestURL>
  <metadataFormat>
    <metadataPrefix>oai_dc</metadataPrefix>
    <schema>http://www.openarchives.org/OAI/2.0/oai_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 for the unique identifier oai:lcoa1:loc.rbc/rbpe.00000111 in the repository http://memory.loc.gov/cgi-bin/oai. The identifier, however, does not exist and therefore, the response contains an error element and no metadataFormat container. [URL shown without encoding for better readability].

http://memory.loc.gov/cgi-bin/oai?
       verb=ListMetadataFormats&identifier=oai:lcoa1:loc.rbc/rbpe.00000111

Response

<?xml version="1.0" encoding="UTF-8"?>
<ListMetadataFormats xmlns="http://www.openarchives.org/OAI/2.0/" 
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                     xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ 
                     http://www.openarchives.org/OAI/2.0/OAI_ListMetadataFormats.xsd">
  <responseDate>2002-06-08T15:19:13Z</responseDate>
  <requestURL>http://memory.loc.gov/cgi-bin/oai?verb=ListMetadataFormats
              &amp;identifier=oai%3Alcoa1:loc.rbc%2Frbpe.00000111</requestURL>
  <error code="idDoesNotExist">oai:lcoa1:loc.rbc/rbpe.00000111 has the structure 
   of a valid LOC identifier, but it maps to no known item</error>
</ListMetadataFormats>

4.5. ListRecords

Summary and Usage Notes

This verb is used to harvest records from a repository. Optional arguments permit selective 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 UTCdatetime 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 UTCdatetime 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 an incomplete list.
metadataPrefix a required argument (unless the exclusive argument resumptionToken is used) that specifies the metadataPrefix of the format that should be included in the metadata part of the returned records. The metadata formats supported by a repository and for a particular record can be retrieved using the ListMetadataFormats request.

Error Conditions

badArgument - The request includes illegal arguments or is missing required arguments.
badGranularity - The values of the from and until arguments are illegal or specify a finer granularity than is supported by the repository.
badResumptionToken - The value of the resumptionToken argument is invalid or expired.
cannotDisseminateFormat - The value of the metadataPrefix argument is not supported by the repository.
noRecordsMatch - The combination of the values of the from, until, and set arguments results in an empty list.

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/2.0/"
        targetNamespace="http://www.openarchives.org/OAI/2.0/"
        elementFormDefault="qualified" attributeFormDefault="unqualified">

  <annotation>
   <documentation>
     Schema to verify validity of responses to ListRecords OAI-protocol request.
    This Schema validated with XML Spy version 4.2 on 2002-03-01</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="oai:UTCdatetimeType"/>
     <element name="requestURL" minOccurs="1" maxOccurs="1" type="anyURI"/>
     <element name="error" minOccurs="0" maxOccurs="unbounded" type="oai:ListRecordsErrorType"/>
     <element name="record" minOccurs="0" maxOccurs="unbounded" type="oai:recordType"/>
     <element ref="oai:resumptionToken" minOccurs="0" maxOccurs="1" />
   </sequence>
   </complexType>

  <simpleType name="UTCdatetimeType">
    <union memberTypes="date dateTime"/>
  </simpleType>

  <!-- valid error codes for ListRecords -->

    <complexType name="ListRecordsErrorType">
      <simpleContent>
        <extension base="string">
          <attribute name="code" type="oai:ListRecordsErrorcodeType" use="required"/>
        </extension>
      </simpleContent>
    </complexType>
	
  <simpleType name="ListRecordsErrorcodeType">
    <restriction base="string">
      <enumeration value="cannotDisseminateFormat"/>
      <enumeration value="noRecordsMatch"/>
      <enumeration value="badArgument"/>
      <enumeration value="badGranularity"/>
      <enumeration value="badResumptionToken"/>
    </restriction>
  </simpleType>

  <!-- 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="unbounded" type="oai:aboutType"/>
    </sequence>
      <attribute name="status" use="optional" type="oai:statusType"/>
  </complexType>

  <!-- define headerType -->
  <!-- a header has a unique identifier, a datestamp, and setSpec(s) in case the record belongs to set(s) -->

  <complexType name="headerType">
    <sequence>
      <element name="identifier" type="anyURI"/>
      <element name="datestamp" type="oai:oaiDateTimeType"/>
      <element name="setSpec" type="oai:setSpecType" minOccurs="0" maxOccurs="unbounded"/>
    </sequence>
  </complexType>
  
  <simpleType name="oaiDateTimeType">
    <union memberTypes="date dateTime"/>
  </simpleType>

  <simpleType name="setSpecType">
    <restriction base="string">
      <pattern value="([A-Za-z0-9_!\-\.\*])+(:[A-Za-z0-9A-Za-z0-9_!\-\.\*]+)*"/>
    </restriction>
  </simpleType>

  <!-- define metadataType -->
  <!-- metadata must be expressed in XML that complies with another XML Schema -->
  <!-- metadata must be explicitely 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>

  <!-- define resumptionToken - with 4 optional attributes -->

  <element name="resumptionToken">
    <complexType>
      <attribute name="resumeAfter" type="positiveInteger"/>
      <attribute name="expirationDate" type="oai:UTCdatetimeType" use="optional"/>
      <attribute name="completeListSize" type="positiveInteger" use="optional"/>
      <attribute name="cursor" type="nonNegativeInteger" use="optional"/>
    </complexType>
  </element>

</schema>

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

Examples

Request

List the records from which oai_rfc1807 metadata can be disseminated, and that have been added or modified since January 15, 1998 in the hep subset 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

Two records are returned:

The first includes the oai_rfc1807 metadata. This record also has an about part, and it belongs to two sets (physics:hep and math)
The second has a status="deleted" attribute (and therefore no metadata part).

Note: The reply only includes records from which metadata in oai_rfc1807 can be disseminated. Other records that fit the from, until, and set arguments but can not be disseminated in the specified metadata format are not returned.

<?xml version="1.0" encoding="UTF-8"?>
<ListRecords xmlns="http://www.openarchives.org/OAI/2.0/"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/     
             http://www.openarchives.org/OAI/2.0/OAI_ListRecords.xsd">
  <responseDate>2002-06-01T19:20:30Z</responseDate> 
  <requestURL>http://an.oa.org/OAI-script?verb=ListRecords
                &from=1998-01-15&setSpec=physics%3Ahep
                &metadataPrefix=oai_rfc1807</requestURL>
  <record>
    <header>
      <identifier>oai:arXiv:hep-th/9901001</identifier>
      <datestamp>1999-12-25</datestamp>
      <setSpec>physics:hep</setSpec>
      <setSpec>math</setSpec>
    </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>
      <oaidc:oai_dc xmlns:oaidc="http://www.openarchives.org/oaidc/" 
                    xmlns:dc="http://purl.org/dc/elements/1.1/" 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:schemaLocation="http://www.openarchives.org/oaidc/ 
                    http://www.openarchives.org/OAI/2.0/oai_dc.xsd">
        <dc:publisher>Los Alamos arXiv</dc:publisher>
        <dc:rights>Metadata may be used without restrictions as long as the oai 
         identifier remains attached to it.</dc:rights>
      </oaidc:oai_dc>
    </about>
  </record>
  <record status="deleted">
    <header>
      <identifier>oai:arXiv:hep-th/9901007</identifier>
      <datestamp>1999-12-21</datestamp>
    </header>
  </record>
</ListRecords>

Request

Request records modified or added between 2:15 and 2:20 PM UTC on May 1st 2002, from which the oai_dc metadata format can be disseminated. [URL shown without encoding for better readability].

http://www.perseus.tufts.edu/cgi-b:in/pdataprov?
       verb=ListRecords&from=2002-05-01T14:15Z&until=2002-05-01T14:20Z&metadataPrefix=oai_dc

Response

Two records are returned. The second one has a provenance container in its about element, which provides information regarding the origin of the record. It seems that the metadata in the second record has its origins in records from 2 other repositories.

<?xml version="1.0" encoding="UTF-8"?>
<ListRecords xmlns="http://www.openarchives.org/OAI/2.0/"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/         
             http://www.openarchives.org/OAI/2.0/OAI_ListRecords.xsd">
  <responseDate>2002-06-01T19:20:30Z</responseDate> 
  <requestURL>http://www.perseus.tufts.edu/cgi-bin/pdataprov?verb=ListRecords
              &from=2002-05-01T14:15Z&until=2002-05-01T14:20Z
              &metadataPrefix=oai_dc</requestURL>
  <record>
    <header>
      <identifier>oai:perseus:Perseus:text:1999.02.0084</identifier>
      <datestamp>2002-05-01T14:16:12Z</datestamp>
    </header>
    <metadata>
      <oaidc:oai_dc xmlns:oaidc="http://www.openarchives.org/oaidc/" 
                    xmlns:dc="http://purl.org/dc/elements/1.1/" 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:schemaLocation="http://www.openarchives.org/oaidc/ 
                    http://www.openarchives.org/OAI/2.0/oai_dc.xsd">
        <dc:title>Opera Minora</dc:title>
        <dc:creator>Cornelius Tacitus</dc:creator>
        <dc:type>text</dc:type>
        <dc:source>Opera Minora. Cornelius Tacitus. Henry Furneaux. 
         Clarendon Press. Oxford. 1900.</dc:source>
        <dc:language>latin</dc:language>
        <dc:identifier>http://www.perseus.tufts.edu/cgi-bin/ptext?
          doc=Perseus:text:1999.02.0084</dc:identifier>
      </oaidc:oai_dc>
    </metadata>
  </record>
  <record>
    <header>
      <identifier>oai:perseus:Perseus:text:1999.02.0083</identifier>
      <datestamp>2002-05-01T14:20:55Z</datestamp></header>
    <metadata>
      <oaidc:oai_dc xmlns:oaidc="http://www.openarchives.org/oaidc/" 
                    xmlns:dc="http://purl.org/dc/elements/1.1/" 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:schemaLocation="http://www.openarchives.org/oaidc/ 
                    http://www.openarchives.org/OAI/2.0/oai_dc.xsd">
        <dc:title>Germany and its Tribes</dc:title>
        <dc:creator>Tacitus</dc:creator>
        <dc:type>text</dc:type>
        <dc:source>Complete Works of Tacitus. Tacitus. Alfred John Church. 
         William Jackson Brodribb. Lisa Cerrato. edited for Perseus. 
         New York: Random House, Inc. Random House, Inc. reprinted 1942.</dc:source>
        <dc:language>english</dc:language>
        <dc:identifier>http://www.perseus.tufts.edu/cgi-bin/ptext?
         doc=Perseus:text:1999.02.0083</dc:identifier>
      </oaidc:oai_dc>
      </metadata>
    <about>
      <provenance xmlns="http://www.openarchives.org/OAI/2.0/provenance" 
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                  xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/provenance
                  http://www.openarchives.org/OAI/2.0/OAI_provenance.xsd">
        <originDescription>
          <baseURL>http://an.oa.org</baseURL>
          <identifier>oai:r1:plog/9801001</identifier>
          <metadataPrefix>oai_dc</metadataPrefix>
          <datestamp>2001-08-13T13:00:02Z</datestamp>
          <harvestDate>2001-08-15T12:01:30Z</harvestDate>
        </originDescription>
        <originDescription>
          <baseURL>http://the.oa.org</baseURL>
          <identifier>oai:r2:klik001</identifier>
          <metadataPrefix>oai_dc</metadataPrefix>
          <datestamp>2002-01-01</datestamp>
          <harvestDate>2002-02-02T14:10:02Z</harvestDate>
        </originDescription>
      </provenance>
    </about>
  </record>
</ListRecords>

Request

Request records modified or added between 2:00 and 3:00 AM UTC on June 1st 2002, from which the oai_marc metadata format can be disseminated. The specified granularity is not supported by the repository and therefore, an error with code attribute of badGranularity is returned. [URL shown without encoding for better readability].

http://memory.loc.gov/cgi-bin/oai?
       verb=ListRecords&from=2002-06-01T02:00Z&until=2002-06-01T03:00Z&metadataPrefix=oai_marc

Response

<?xml version="1.0" encoding="UTF-8"?>
<ListRecords xmlns="http://www.openarchives.org/OAI/2.0/" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
             xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ 
             http://www.openarchives.org/OAI/2.0/OAI_ListRecords.xsd">
  <responseDate>2002-06-01T19:20:30Z</responseDate> 
  <requestURL>http://memory.loc.gov/cgi-bin/oai?verb=ListRecords
              &from=2002-06-01T02:00Z&until=2002-06-01T03:020Z
              &metadataPrefix=all</requestURL>
  <error code="badGranularity"/>
</ListRecords>

4.6. ListSets

Summary and Usage Notes

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

Arguments

resumptionToken an exclusive argument with a value that is the flow control token returned by a previous ListSets request that issued an incomplete list

Error Conditions

badArgument - The request includes illegal arguments or is missing required arguments.
badResumptionToken - The value of the resumptionToken argument is invalid or expired.
noSetHierarchy - The repository does not support sets.

Response Format

A XML schema for validating the response is as follows:

<schema targetNamespace="http://www.openarchives.org/OAI/2.0/" 
        xmlns:oai="http://www.openarchives.org/OAI/2.0/" 
        xmlns="http://www.w3.org/2001/XMLSchema" 
        elementFormDefault="qualified" attributeFormDefault="unqualified">

  <annotation>
    <documentation>
     Schema to verify validity of responses to ListSets OAI-protocol request.
     This Schema validated with XML Spy version 4.2 on 2002-03-01</documentation>
  </annotation>

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

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

  <complexType name="ListSetsType">
    <sequence>
      <element name="responseDate" type="oai:UTCdatetimeType"/>
      <element name="requestURL" type="anyURI"/>
      <element name="error" type="oai:ListSetsErrorType" minOccurs="0" maxOccurs="unbounded"/>
      <element name="set" type="oai:setType" minOccurs="0" maxOccurs="unbounded"/>
      <element ref="oai:resumptionToken" minOccurs="0" maxOccurs="1"/>
    </sequence>
  </complexType>

  <simpleType name="UTCdatetimeType">
    <union memberTypes="date dateTime"/>
  </simpleType>

<!-- valid error codes for ListSets -->

  <complexType name="ListSetsErrorType">
    <simpleContent>
      <extension base="string">
        <attribute name="code" type="oai:ListSetsErrorcodeType" use="required"/>
      </extension>
    </simpleContent>
  </complexType>

  <simpleType name="ListSetsErrorcodeType">
    <restriction base="string">
      <enumeration value="noSetHierarchy"/>
      <enumeration value="badResumptionToken"/>
      <enumeration value="badArgument"/>
    </restriction>
  </simpleType>

  <!-- each set in the list consists of a setSpec, a pretty name, 
  and a repeatable container allowing for descriptions of the set -->

  <complexType name="setType">
    <sequence>
      <element name="setSpec" type="oai:setSpecType"/>
      <element name="setName" type="string"/>
      <element name="setDescription" type="oai:setDescriptionType" minOccurs="0" maxOccurs="unbounded"/>
    </sequence>
  </complexType>

  <simpleType name="setSpecType">
    <restriction base="string">
      <pattern value="([A-Za-z0-9_!\-\.\*])+(:[A-Za-z0-9A-Za-z0-9_!\-\.\*]+)*"/>
    </restriction>
  </simpleType>

  <complexType name="setDescriptionType">
    <sequence>
      <any namespace="##other" processContents="lax"/>
    </sequence>
  </complexType>

  <!-- define resumptionToken - with 4 optional attributes -->

  <element name="resumptionToken">
    <complexType>
      <attribute name="resumeAfter" type="positiveInteger"/>
      <attribute name="expirationDate" type="oai:UTCdatetimeType" use="optional"/>
      <attribute name="completeListSize" type="positiveInteger" use="optional"/>
      <attribute name="cursor" type="nonNegativeInteger" use="optional"/>
    </complexType>
  </element>

</schema>

This Schema is available at http://www.openarchives.org/OAI/2.0/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 with respective setSpec music and video. The music set has two subsets, with setSpec music:muzak and music:elec. One of the subsets, music:elec, has a setDescription element which holds a Dublin Core container, used to describe its contents.

<?xml version="1.0" encoding="UTF-8"?>
<ListSets xmlns="http://www.openarchives.org/OAI/2.0/" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ 
          http://www.openarchives.org/OAI/2.0/OAI_ListSets.xsd">
  <responseDate>2002-08-11T07:21:33Z</responseDate>
  <requestURL>http://an.oa.org/OAI-script?verb=ListSets</requestURL>
  <set>
    <setSpec>music</setSpec>
    <setName>Music collection</setName>
  </set>
  <set>
    <setSpec>music:muzak</setSpec>
    <setName>Muzak collection</setName>
  </set>
  <set>
    <setSpec>music:elec</setSpec>
    <setName>Electronic Music Collection</setName>
    <setDescription>
      <oaidc:oai_dc xmlns:oaidc="http://www.openarchives.org/oaidc/" 
                    xmlns:dc="http://purl.org/dc/elements/1.1/" 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:schemaLocation="http://www.openarchives.org/oaidc/ 
                    http://www.openarchives.org/OAI/2.0/oai_dc.xsd">
          <dc:description>This set contains metadata describing electronic 
              music recordings made during the 1950ies</dc:description>
       </oaidc:oai_dc>
    </setDescription>
   </set>
   <set>
    <setSpec>video</setSpec>
    <setName>Video Collection</setName>
   </set>
</ListSets>

Request

http://purl.org/alcme/etdcat/servlet/OAIHandler?
       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/2.0/"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/        
          http://www.openarchives.org/OAI/2.0/OAI_ListSets.xsd">
  <responseDate>2001-06-01T19:20:30Z</responseDate> 
  <requestURL>http://purl.org/alcme/etdcat/servlet/OAIHandler?
              verb=ListSets</requestURL>
  <error code="noSetHierarchy">This repository does not support sets</error>
</ListSets>

5. Dublin Core

The following table shows the XML Schema for Dublin Core without qualification, which is associated with the reserved metadataPrefix oai_dc in the OAI-PMH. All examples in this document that include Dublin Core metadata, validate against this XML schema. Schema for other metadata formats are provided in the accompanying Implementation Guidelines document.

A XML schema for validating Unqualified Dublin Core metadata associated with the reserved oai_dc metadataPrefix

<xs:schema targetNamespace="http://www.openarchives.org/oaidc/" 
           xmlns="http://www.openarchives.org/oaidc/" 
           xmlns:dc="http://purl.org/dc/elements/1.1/" 
           xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           elementFormDefault="qualified" attributeFormDefault="unqualified">

  <xs:annotation>
    <xs:documentation> 
      XML Schema 2002-02-07 by Pete Johnston.
      Adjusted on 2002-02-19 for usage in the OAI-PMH.
      Schema defines the wrapper element "oai_dc", 
       which can have elements from DC namespace as children.
    </xs:documentation>
  </xs:annotation>


  <xs:import namespace="http://purl.org/dc/elements/1.1/" 
           schemaLocation="http://www.ukoln.ac.uk/metadata/dcmi/dcxml/xmls/simpledc.xsd"/>

  <xs:element name="oai_dc">
   <xs:complexType>
     <xs:choice>
       <xs:group ref="dc:elementsGroup"/>
     </xs:choice>
   </xs:complexType>
  </xs:element>

</xs:schema>

This Schema is available at http://www.openarchives.org/OAI/2.0/oai_dc.xsd

Examples

<?xml version="1.0" encoding="UTF-8"?>
<oaidc:oai_dc xmlns:oaidc="http://www.openarchives.org/oaidc/" 
              xmlns:dc="http://purl.org/dc/elements/1.1/" 
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
              xsi:schemaLocation="http://www.openarchives.org/oaidc/ 
              http://www.openarchives.org/OAI_protocol/2.0/oai_dc.xsd">
  <dc:title xml:lang="en">The Cornell Law Quarterly</dc:title>
  <dc:date>1915-1916</dc:date>
  <dc:identifier>http://heinonline.org/HeinOnline/show.pl?
      handle=hein.journals/clqv1%26id=1%26size=4</dc:identifier>
  <dc:rights>Available by Subscription. See http://www.wshein.com</dc:rights>
</oaidc:oai_dc>

<?xml version="1.0" encoding="UTF-8"?>
<oaidc:oai_dc xmlns:oai="http://www.openarchives.org/oaidc/" 
            xmlns:dc="http://purl.org/dc/elements/1.1/" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xsi:schemaLocation="http://www.openarchives.org/oaidc/
            http://www.openarchives.org/OAI_protocol/2.0/oai_dc.xsd">
  <dc:title xml:lang="en">Grassmann's space analysis</dc:title>
  <dc:creator>Hyde, E. W. (Edward Wyllys)</dc:creator>
  <dc:subject>LCSH:Ausdehnungslehre; LCCN QA205.H99</dc:subject>
  <dc:publisher>J. Wiley & Sons</dc:publisher>
  <dc:date>Created: 1906; Available: 1991</dc:date>
  <dc:type>text</dc:type>
  <dc:identifier>http://resolver.library.cornell.edu/math/1796949</dc:identifier>
  <dc:language>english</dc:language>
  <dc:rights xml:lang="en">Public Domain</dc:rights>
</oaidc:oai_dc>

6. Implementation Guidelines

Some passages in this document refer to the existence and goals of the accompanying Implementation Guidelines document.

Acknowledgements

Support for the compilation of this document and for other Open Archives Initiative activities comes from the Digital Library Federation and the Coalition for Networked Information. Additional support for work on Open Archives Initiatives protocols comes from National Science Foundation Grant No. IIS-9817416 and Defense Advanced Projects Agency Grant No. N66001-98-1-8908.

This document is based on the deliberations of the OAI Technical Committee:

Caroline Arms	<caar@loc.gov>	Library of Congress
Thomas Baron	<thomas.baron@cern.ch>	CERN
Steven Bird	<sb@ldc.upenn.edu>	University of Pennsylvania
Les Carr	<lac@ecs.soton.ac.uk>	University of Southampton
Tim Cole	<t-cole3@uiuc.edu>	University of Illinois at Urbana Champaign
Thomas Krichel	<krichel@openlib.org>	Long Island University
Carl Lagoze	<lagoze@cs.cornell.edu>	Cornell University
Michael Nelson	<m.l.nelson@larc.nasa.gov>	NASA
Andy Powell	<a.powell@ukoln.ac.uk>	UKOLN
Mogens Sandfaer	<ms@dtv.dk>	Danmarks Tekniske Videncenter
Hussein Suleman	<hussein@vt.edu>	Virginia Tech
Robert Tansley	<Robert_Tansley@hplb.hpl.hp.com>	HP
Herbert Van de Sompel	<hvdsomp@yahoo.com>	Los Alamos National Laboratory
Simeon Warner	<simeon@cs.cornell.edu>	Cornell University
Muhammad Zubair	<zubair@cs.odu.edu>	Old Dominion University
Jeff Young	<jyoung@oclc.org>	OCLC

Must include reference to parties participating in alpha test of 2.0.

Many thanks to everyone involved in the compilation and alpha-testing of version 1.0 and 1.1 of the OAI-PMH. And to all of you using this protocol.

Document History

2002-03-01: Release of alpha version of OAI-PMH version 2.0

	The Open Archives Initiative Protocol for Metadata Harvesting
	Protocol Version 2.0A of 2002-03-01 Document Version version 2002-03-01 10:00:00Z - hvds http://www.openarchives.org/OAI/openarchivesprotocol.htm Previous version: Protocol Version 1.1 of 2001-07-02 Instructions for migrating from Version 1.1 to 2.0
	Alpha version. Do not distribute.

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

Error Codes	Description	Applicable Verbs
badArgument	The request includes illegal arguments or is missing required arguments.	all verbs
badGranularity	The values of the from and until arguments are illegal or specify a finer granularity than is supported by the repository.	ListIdentifiers ListRecords
badResumptionToken	The value of the resumptionToken argument is invalid or expired.	ListIdentifers ListRecords ListSets
badVerb	Value of the verb argument is not a legal OAI-PMH verb or the verb argument is missing. The badVerb error is contained within an Identify verb response.	N/A
cannotDisseminateFormat	The value of the metadataPrefix argument is not supported by the repository.	GetRecord ListIdentifiers ListRecords
idDoesNotExist	The value of the identifier argument is unknown or illegal in this repository.	GetRecord ListMetadataFormats
noRecordsMatch	The combination of the values of the from, until, set and metadataPrefix arguments results in an empty list.	ListIdentifiers ListRecords
noSetHierarchy	The repository does not support sets.	ListSets

The Open Archives Initiative Protocol for Metadata Harvesting

Protocol Version 2.0A of 2002-03-01 Document Version version 2002-03-01 10:00:00Z - hvds http://www.openarchives.org/OAI/openarchivesprotocol.htmPrevious version: Protocol Version 1.1 of 2001-07-02Instructions for migrating from Version 1.1 to 2.0

Alpha version. Do not distribute.

1. Introduction

2. Definitions and Concepts

2.1 Repository

2.2 Harvester

2.3 Record

2.3.1 Deleted Records

2.4 Unique Identifier

2.5 Datestamp

2.6 Set

3.0 Protocol Features

3.1 HTTP embedding of OAI-PMH requests

3.1.1 HTTP Request Format

3.1.1.1 Encoding an OAI-PMH request in a URL for an HTTP GET

3.1.1.2 Encoding an OAI-PMH request in an HTTP POST

3.1.1.3 Encoding of special characters in keyword arguments of OAI-PMH requests

3.1.2 HTTP Response Format

3.1.2.1 Content-Type

3.1.2.2 Status-Code

3.1.3 Response Compression

3.2 UTCdatetime

3.2.1 UTCdatetime in Protocol Requests

3.2.2 UTCdatetime in Protocol Responses

3.3 metadataPrefix and Metadata Schema

3.4 Flow Control

3.5 Error Conditions

Request

Request

4. Protocol Requests and Responses

4.1. GetRecord

Summary and Usage Notes

Arguments

Error Conditions

Response Format

Examples

Request

Response

Request

Response

Request

Response

4.2. Identify

Summary and Usage Notes

Arguments

Error Conditions

Response Format

Examples

Request

Response

4.3. ListIdentifiers

Summary and Usage Notes

Arguments

Error Conditions

Response Format

Examples

Request

Response

Request

Response

Request

Response

4.4. ListMetadataFormats

Summary and Usage Notes

Arguments

Error Conditions

Response Format

Examples

Request

Response

Request

Response

Request

Response

4.5. ListRecords

Summary and Usage Notes

Arguments

Error Conditions

Response Format

Protocol Version 2.0A of 2002-03-01
Document Version version 2002-03-01 10:00:00Z - hvds
http://www.openarchives.org/OAI/openarchivesprotocol.htm

Previous version: Protocol Version 1.1 of 2001-07-02
Instructions for migrating from Version 1.1 to 2.0