The Open Archives Initiative Protocol for Metadata Harvesting | |
Protocol Version 2.0A-2 of 2002-03-30 | |
Alpha version. Do not distribute. |
Editors
The OAI Executive:
Carl
Lagoze <lagoze@cs.cornell.edu> -- Cornell University - Computer
Science
Herbert Van de
Sompel <hvdsomp@yahoo.com> --
Los Alamos National Laboratory - Research
Library
From the OAI Technical Committee:
Michael Nelson <m.l.nelson@larc.nasa.gov> -- NASA - Langley Research Center
Simeon Warner <simeon@cs.cornell.edu> -- Cornell University - Computer Science
Table of Contents
1. Introduction
2. Definitions and Concepts
2.1. Harvester
2.2. Repository
2.3. Item
2.3.1. Deleted
Items
2.4. Unique
Identifier
2.5. Datestamp
2.6. Record
2.7. Set
3. Protocol Features
3.1. HTTP embedding of OAI-PMH
requests
3.1.1.
HTTP Request Format
3.1.2.
HTTP Response Format
3.1.3.
Response Compression
3.2. XML Response Format
3.3. UTCdatetime
3.3.1.
UTCdatetime in Protocol Requests
3.3.2.
UTCdatetime in Protocol Responses
3.4. metadataPrefix and Metadata Schema
3.5. Flow
Control
3.5.1
Idempotency of resumptionTokens
3.6. Error
Conditions
4. Protocol
Requests and Responses
4.1. GetRecord
4.2. Identify
4.3. ListIdentifiers
4.4.
ListMetadataFormats
4.5. ListRecords
4.6. ListSets
5. Dublin
Core
6. Implementation
Guidelines
Acknowledgements
Document
History
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.
A harvester is a client application that issues OAI-PMH requests. A harvester is operated by a service provider as a means of collecting metadata from repositories.
A repository is a network accessible server that can process the 6 OAI-PMH requests in the manner described in this document. A repository is managed by a data provider to expose metadata to harvesters. To allow various repository configurations, the OAI-PMH distinguishes between three distinct entities related to the metadata made accessible by the OAI-PMH.
A repository may indicate that an item has a deleted status. This status indicates that an item is no longer a constituent of the repository and hence no metadata can be disseminated from it. When appropriate the deleted status is indicated via an attribute in the header in the response to the ListIdentifiers, GetRecord and ListRecords requests.
Repositories must express the nature of their support of the deleted status as part of the Identify response. Three levels of support are defined:
A unique identifier unambigiously identifies an item within a repository; the unique identifier is used in OAI-PMH requests for extracting metadata from the 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.
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. Repositories may implement the oai-identifier syntax described in the accompanying Implementation Guidelines document.
Unique identifiers play two roles in the protocol:
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 to the resource associated with harvested metadata, repositories should use an element in metadata records to establish a linkage between the record (and the identifier of its item) 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.
A datestamp is a date and time useful for selective harvesting based on the instant of changes to items in the repository. Every item header returned by the GetRecord, ListRecords, or ListIdentifiers requests contains a datestamp. A repository must set or change the datestamp to indicate creation or modification of an item. If a repository supports the optional notion of deleted items, then it must also change the datestamp to indicate the deletion of the 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.
The following example shows a record and its components:
<header> <identifier>oai:arXiv:cs/0112017</identifier> <datestamp>2002-02-28</datestamp> <setSpec>cs</setSpec> <setSpec>math</setSpec> </header> <metadata> <oai_dc:dc xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc/oai_dc.xsd"> <dc:title>Using Structural Metadata to Localize Experience of Digital Content</dc:title> <dc:creator>Dushay, Naomi</dc:creator> <dc:subject>Digital Libraries</dc:subject> <dc: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. </dc:description> <dc:description>Comment: 23 pages including 2 appendices, 8 figures</dc:description> <dc:date>2001-12-14</dc:date> <dc:type>e-print</dc:type> <dc:identifier>http://arXiv.org/abs/cs/0112017</dc:identifier> </oai_dc: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/provenance/oai_provenance.xsd"> <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> |
A set is an optional construct for grouping items for the purpose of selective harvesting. Repositories may organize items into sets. Set organization may be flat, i.e. a simple list, or hierarchical. Multiple hierarchies with distinct, independent top-level nodes are allowed. Hierarchical organization of sets is expressed in the syntax of the setSpec parameter as described below. When a repository defines a set organization it must include set membership information in the headers of items returned in response to the ListIdentifiers, ListRecords and GetRecord requests.
Each node in a set organization of a repository has:
The following is an example of a possible set hierarchy in a repository:
The following table shows a possible representation of the above set hierarchy by means of setNames and respective setSpecs.
setName |
setSpec |
Institutions | institution |
Oceanside University of Nebraska |
institution:nebraska |
Valley View University of Florida |
institution:florida |
Subjects | subject |
Existential Kenesiology |
subject:kenesiology |
Quantum Psychology |
subject:quantum |
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 metadata from all items 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 setNames and setSpec, 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 a list indicating the configuration of sets in a repository. Each member of this list must include a setSpec and 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:
In addition to the base URL, all requests consist of a list of keyword arguments, which take the form of 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.
However, since special characters in URIs must be encoded, the correct form of the above GET request URL is:
http://an.oa.org/OAI-script?
verb=GetRecord&identifier=oai%3AarXiv%3Ahep-th%2F9901001&metadataPrefix=oai_dc
Keyword arguments are carried in the message body of the HTTP POST. The Content-Type of the request must be application/x-www-form-urlencoded. For example, submitting the same request as above using the POST method would use just the 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
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-PMH, this means that the reserved characters must be encoded when they appear in the value part of the key=value pairs of the request. This applies for both the GET and POST encoding of the OAI-PMH requests.
The Content-Type returned for all OAI-PMH requests must be text/xml.
503 - Service unavailable, a Retry-After period is specified. Harvesters should wait this period before attempting another OAI-PMH request.
Response compression is optional in OAI-PMH. Compression of responses to OAI-PMH requests is handled at the level of HTTP, with the following restrictions:
All responses to OAI-PMH requests must be well-formed XML instance documents. Encoding of the XML must use the UTF-8 representation of Unicode. 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 XML data for all responses must have the following common markup:
In the case of an error condition the next element must be an error element that indicates the nature of the error.
An example of a successful reply to the GetRecord request shown above is of the form:
<?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-05-01T19:20:30Z</responseDate> <requestURL>http://an.oa.org/OAI-script?verb=GetRecord &identifier=oai%3AarXiv%3Ahep-th%2F9901001 &metadataPrefix=oai_dc</requestURL> <record>...</record> </GetRecord> |
Dates and times are uniformly encoded using ISO8601 and are expressed in UTC throughout the protocol. When time is included, the special UTC designator ("Z") must be used. For example, 1957-03-20T20:30:00.00Z is UTC 8:30:00.00 PM on March 20th 1957. UTCdatetime is used in both protocol requests and protocol replies, in the way described in the following sections.
Datestamps used as values of the optional arguments from and until in the ListIdentifiers and ListRecords requests are encoded using ISO8601 and are expressed in UTC. These arguments are used to specify time-range harvesting. These arguments support the multiple granularities defined in ISO8601. The legitimate formats are YYYY ; YYYY-MM ; YYYY-MM-DD ; YYYY-MM-DDThh:mmZ ; YYYY-MM-DDThh:mm:ssZ; and YYYY-MM-DDThh:mm:ss.sZ. Both arguments must have the same granularity. No distinction is made between whole seconds and decimal seconds formats; both are permitted with YYYY-MM-DDThh:mm:ssZ granularity and may be inter-mixed. All repositories must support YYYY; YYYY-MM; and YYYY-MM-DD.
A repository that supports a granularity finer than YYYY-MM-DD should expose the finest granularity that it supports in the Identify response. Harvester requests with coarser granularity than the finest supported by the repository should be interpreted appropriately. For example, the range from=2001-01 and until=2001-01 should be interpreted as from=2001-01-01T00:00:00Z and until=2001-01-31T23:59:59Z in a repository that supports seconds. A request by a harvester with finer granularity than that supported by a repository must produce an error.
Datestamps appear in the headers of records that are returned in response to ListIdentifiers, 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 may include 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.
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 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. metadataPrefixes can also used in the ListIdentifiers request as a means to request headers of those items from which the metadata format identified by the value provided for metadataPrefix argument can be disseminated.
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 must 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/oai_dc.xsd. The corresponding XML namespace URI is http://www.openarchives.org/OAI/2.0/oai_dc/ .
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.
A number of OAI-PMH requests return a list of discrete entities: ListRecords returns a list of records, ListIdentifiers returns a list of headers, and ListSets returns a list of sets. Collectively these requests are called list requests. 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:
Details of flow control and the resumptionToken are as follows:
The following optional attributes may be included as part of the resumptionToken element along with the resumptionToken itself:
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.
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.
Repositories that implement resumptionTokens must do so in a manner that allows harvesters to resume a sequence of requests for incomplete lists by re-issuing a list request with the most recent resumptionToken. The purpose of this is to allow harvesters to recover from network or other errors that would otherwise mean that the list request sequence would have to be started again. A re-issue of a list request with a resumptionToken occurs in two contexts:
In event of an error condition, 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 the OAI-PMH.
Repositories must respond to requests containing an illegal value for the verb argument by sending an Identify response with the inclusion of an error element containing the badVerb value as code attribute.
Error Codes | Description | Applicable Verbs |
badArgument | The request includes illegal arguments, is missing required arguments, includes a repeated argument, or values for argunents have an illegal syntax. | 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, the verb argument is missing, or the verb argument is repeated. The badVerb error is contained within an Identify response. | N/A |
cannotDisseminateFormat |
The metadata format identified by the value given for the metadataPrefix argument is not supported by the item or by the repository. | GetRecord ListIdentifiers ListRecords |
idDoesNotExist |
The value of the identifier argument is unknown or illegal in this repository. | GetRecord ListMetadataFormats |
noItemsMatch |
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. All request URLs shown from now on will be wrapped to support a better readibility.
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> <earliestDatestamp>1988-01-10</earliestDatestamp> <deletedItem>no</deletedItem> <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.
http://arXiv.org/oai2? verb=ListSets
<?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> |
This verb is used to retrieve an individual metadata record from an item in a repository. Required arguments specify the identifier of the item from which the record is requested and the format of the metadata that should be included in the record. If the specified item is known to be deleted from the repository, a header with a "deleted" value for the status attribute must be returned.
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> </complexType> <!-- define headerType --> <!-- a header has a unique identifier, a datestamp, and setSpec(s) in case the item from which the record is disseminated belongs to set(s). the header can carry a deleted status indicatat the item identified in the header is deleted. --> <complexType name="headerType"> <sequence> <element name="identifier" type="anyURI"/> <element name="datestamp" type="oai:UTCdatetimeType"/> <element name="setSpec" type="oai:setSpecType" minOccurs="0" maxOccurs="unbounded"/> </sequence> <attribute name="status" type="oai:statusType" use="optional"/> </complexType> <simpleType name="setSpecType"> <restriction base="string"> <pattern value="([A-Za-z0-9_!'$\(\)\+\-\.\*])+(:[A-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="1" maxOccurs="1"/> </sequence> </complexType> <!-- define statusType --> <!-- the item from which the record is disseminated 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 |
http://arXiv.org/oai2? verb=GetRecord&identifier=oai:arXiv:cs/0112017&metadataPrefix=oai_dc
<?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 &identifier=oai%3AarXiv%3Acs%2F0112017 &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> <oai_dc:dc xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc/oai_dc.xsd"> <dc:title>Using Structural Metadata to Localize Experience of Digital Content</dc:title> <dc:creator>Dushay, Naomi</dc:creator> <dc:subject>Digital Libraries</dc:subject> <dc: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.</dc:description> <dc:description>Comment: 23 pages including 2 appendices, 8 figures</dc:description> <dc:date>2001-12-14</dc:date> </oai_dc:dc> </metadata> </record> </GetRecord> |
http://arXiv.org/oai2? verb=GetRecord&identifier=oai:arXiv:quant-ph/02131001&metadataPrefix=oai_dc
<?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 &identifier=oai%3AarXiv%3Aquant-ph%2F0213001 &metadataPrefix=oai_dc</requestURL> <error code="idDoesNotExist">No matching identifier in arXiv</error> </GetRecord> |
http://arXiv.org/oai2? verb=GetRecord&identifier=oai:arXiv:quant-ph/9901001&metadataPrefix=oai_marc
<?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 &identifier=oai%3AarXiv%3Aquant-ph%2F9901001 &metadataPrefix=oai_marc</requestURL> <error code="cannotDisseminateFormat"/> </GetRecord> |
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.
None
The response must include one instance of the following elements:
The response must include one or more instances of the following element:
The response may include one instance of the following optional element:
The response may include multiple instances of the following optional elements:
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-23</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" minOccurs="1" maxOccurs="unbounded"/> <element name="earliestDatestamp" type="oai:UTCdatetimeType"/> <element name="deletedItem" type="oai:deletedItemType"/> <element name="granularity" type="oai:granularityType" minOccurs="0" maxOccurs="1"/> <element name="compression" type="string" 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"> <restriction base="string"> <pattern value="\S+@(\S+\.)+\S+"/> </restriction> </simpleType> <simpleType name="deletedItemType"> <restriction base="string"> <enumeration value="no"/> <enumeration value="persistent"/> <enumeration value="transient"/> </restriction> </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> </schema> |
This Schema is available at http://www.openarchives.org/OAI/2.0/OAI_Identify.xsd |
http://memory.loc.gov/cgi-bin/oai? verb=Identify
<?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>dwoo@loc.gov</adminEmail> <adminEmail>caar@loc.gov</adminEmail> <earliestDatestamp>1990-02-01</earliestDatestamp> <deletedItem>transient</deletedItem> <granularity>YYYY-MM-DDThh:mmZ</granularity> <compression>deflate</compression> <description> <oai-identifier xmlns="http://www.openarchives.org/OAI/2.0/identifier/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/identifier/ http://www.openarchives.org/OAI/2.0/identifier/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> <description> |
This verb is used to retrieve headers of items in a repository. A header contains the properties of an item that are common to all records disseminated from the item: identifier, datestamp and set membership. Optional arguments permit selective retrieval of headers based on the membership of items in a specific set of the repository, the availability of a specific metadata format for items, or based on their modification, creation, or deletion within a specific date range. If an item matching the request criteria is known to be deleted from the repository, only its header must be returned, with a status attribute that has a value of "deleted".
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 ListIdentifiers OAI-protocol request. This Schema validated with XML Spy version 4.2 on 2002-03-23 </documentation> </annotation> <element name="ListIdentifiers" type="oai:ListIdentifiersType"/> <!-- response to ListIdentifiers-request --> <!-- items can have an optional "deleted" status --> <!-- this response may contain an optional resumptionToken --> <complexType name="ListIdentifiersType"> <sequence> <element name="responseDate" type="oai:UTCdatetimeType"/> <element name="requestURL" type="anyURI"/> <element name="error" type="oai:ListIdentifiersErrorType" minOccurs="0" maxOccurs="unbounded"/> <element name="header" type="oai:headerType" minOccurs="0" maxOccurs="unbounded"/> <element ref="oai:resumptionToken" minOccurs="0"/> </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="noItemsMatch"/> <enumeration value="badGranularity"/> <enumeration value="badResumptionToken"/> <enumeration value="cannotDisseminateFormat"/> <enumeration value="noSetHierarchy"/> </restriction> </simpleType> <!-- define headerType --> <!-- a header has a unique identifier, a datestamp, and setSpec(s) in case the item belongs to set(s). the header can carry a deleted status indicating that the item identified in the header is deleted. --> <complexType name="headerType"> <sequence> <element name="identifier" type="anyURI"/> <element name="datestamp" type="oai:UTCdatetimeType"/> <element name="setSpec" type="oai:setSpecType" minOccurs="0" maxOccurs="unbounded"/> </sequence> <attribute name="status" type="oai:statusType" use="optional"/> </complexType> <simpleType name="setSpecType"> <restriction base="string"> <pattern value="([A-Za-z0-9_!'$\(\)\+\-\.\*])+(:[A-Za-z0-9_!'$\(\)\+\-\.\*]+)*"/> </restriction> </simpleType> <!-- the item can have a status of "deleted" . --> <simpleType name="statusType"> <restriction base="string"> <enumeration value="deleted"/> </restriction> </simpleType> <!-- define resumptionToken - with 3 optional attributes --> <element name="resumptionToken"> <complexType> <simpleContent> <extension base="string"> <attribute name="expirationDate" type="oai:UTCdatetimeType" use="optional"/> <attribute name="completeListSize" type="positiveInteger" use="optional"/> <attribute name="cursor" type="nonNegativeInteger" use="optional"/> </extension> </simpleContent> </co> </schema> |
This Schema is available at http://www.openarchives.org/OAI/2.0/OAI_ListIdentifiers.xsd |
http://an.oa.org/OAI-script? verb=ListIdentifiers&from=1998-01-15&set=physics:hep
A list of four headers is returned. One header has a deleted status, indicating that the item identified in the header has been deleted. In addition, a resumptionToken (non-empty, value xxx45abttyz) has been returned, indicating that the list of headers 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 3 optional attributes: expirationDate indicates that the resumptionToken will become unusable after 11:20 PM UTC on June 1st 2002; 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 &from=1998-01-15&setSpec=physics%3Ahep</requestURL> <header> <identifier>oai:arXiv:hep-th/9801001</identifier> <datestamp>1999-02-23</datestamp> <setSpec>physic:hep</setSpec> </header> <header> <identifier>oai:arXiv:hep-th/9801002</identifier> <datestamp>1999-03-20</datestamp> <setSpec>physic:hep</setSpec> <setSpec>physic:exp</setSpec> </header> <header> <identifier>oai:arXiv:hep-th/9801005</identifier> <datestamp>2000-01-18</datestamp> <setSpec>physic:hep</setSpec> </header> <header status="deleted"> <identifier>oai:arXiv:hep-th/9801010</identifier> <datestamp>1999-02-23</datestamp> <setSpec>physic:hep</setSpec> <setSpec>math</setSpec> </header> <resumptionToken expirationDate="2002-06-01T23:20:00Z" completeListSize="6" cursor="0">xxx45abttyz</resumptionToken> </ListIdentifiers> |
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
Two more headers 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 &resumptionToken=xxx45abttyz</requestURL> <header> <identifier>oai:arXiv:hep-th/9801020</identifier> <datestamp>1999-02-23</datestamp> <setSpec>physic:hep</setSpec> </header> <header> <identifier>oai:arXiv:hep-th/9801060</identifier> <datestamp>1999-02-23</datestamp> <setSpec>physic:hep</setSpec> </header> <resumptionToken completeListSize="6" cursor="4"/> </ListIdentifiers> |
http://www.perseus.tufts.edu/cgi-bin/pdataprov? verb=ListIdentifiers&metadataPrefix=olac&from=2001-01-01&until=2001-01-01&set=Perseus:collection:PersInfo
<?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 &metadataPrefix=olac&from=2001-01-01&until=2001-01-01 &set=Perseus%3Acollection%3APersInfo</requestURL> <error code="noItemsMatch"/> </ListIdentifiers> |
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 item.
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-23</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 |
List the metadata formats that can be disseminated from the repository http://www.perseus.tufts.edu/cgi-bin/pdataprov for the item with 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
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 &identifier=oai%3Aperseus%3APerseus%3Atext%3A1999.02.0119</requestURL> <metadataFormat> <metadataPrefix>oai_dc</metadataPrefix> <schema>http://www.openarchives.org/OAI/2.0/oai_dc/oai_dc.xsd</schema> <metadataNamespace>http://www.openarchives.org/OAI/2.0/oai_dc/</metadataNamespace> </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> |
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
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 item 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/oai_dc.xsd</schema> <metadataNamespace>http://www.openarchives.org/OAI/2.0/oai_dc/</metadataNamespace> </metadataFormat> <metadataFormat> <metadataPrefix>oai_marc</metadataPrefix> <schema>http://www.openarchives.org/OAI/1.1/oai_marc.xsd</schema> </metadataFormat> </ListMetadataFormats> |
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
<?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 &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> |
This verb is used to harvest records from a repository. Optional arguments permit selective harvesting based on the membership of items in a specific set in the repository or based on their modification, creation, or deletion within a specific date range. If an item matching the request criteria is known to be deleted from the repository, only its header must be returned, with a status attribute that has a value of "deleted".
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-23</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="noItemsMatch"/> <enumeration value="badArgument"/> <enumeration value="badGranularity"/> <enumeration value="badResumptionToken"/> <enumeration value="noSetHierarchy"/> </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> </complexType> <!-- define headerType --> <!-- a header has a unique identifier, a datestamp, and setSpec(s) in case the item from which the record is disseminated belongs to set(s). the header can carry a deleted status indicating that the item identified in the header is deleted. --> <complexType name="headerType"> <sequence> <element name="identifier" type="anyURI"/> <element name="datestamp" type="oai:UTCdatetimeType"/> <element name="setSpec" type="oai:setSpecType" minOccurs="0" maxOccurs="unbounded"/> </sequence> <attribute name="status" type="oai:statusType" use="optional"/> </complexType> <simpleType name="setSpecType"> <restriction base="string"> <pattern value="([A-Za-z0-9_!'$\(\)\+\-\.\*])+(:[A-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="1" maxOccurs="1"/> </sequence> </complexType> <!-- define statusType --> <!-- the item from which the record is disseminated can have a status of "deleted" . --> <simpleType name="statusType"> <restriction base="string"> <enumeration value="deleted"/> </restriction> </simpleType> <!-- define resumptionToken - with 3 optional attributes --> <element name="resumptionToken"> <complexType> <simpleContent> <extension base="string"> <attribute name="expirationDate" type="oai:UTCdatetimeType" use="optional"/> <attribute name="completeListSize" type="positiveInteger" use="optional"/> <attribute name="cursor" type="nonNegativeInteger" use="optional"/> </extension> </simpleContent> </complexType> </element> </schema> |
This Schema is available at http://www.openarchives.org/OAI/2.0/OAI_ListRecords.xsd |
http://an.oa.org/OAI-script? verb=ListRecords&from=1998-01-15&set=physics:hep&metadataPrefix=oai_rfc1807
Note: The reply only includes records for those items from which metadata in oai_rfc1807 can be disseminated. No records are returned for those items that fit the from, until, and set arguments but from which the specified format can not be disseminated.
<?xml version="1.0" encoding="UTF-8"?> <ListRecords xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org 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> <oai_dc:dc xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc/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> </oai_dc:dc> </about> </record> <record> <header status="deleted"> <identifier>oai:arXiv:hep-th/9901007</identifier> <datestamp>1999-12-21</datestamp> </header> </record> </ListRecords> |
http://www.perseus.tufts.edu/cgi-b:in/pdataprov? verb=ListRecords&from=2002-05-01T14:15Z&until=2002-05-01T14:20Z&metadataPrefix=oai_dc
Two records are returned. The second one has a provenance
container in its about
element, indicating 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%3A15Z&until=2002-05-01T14%3A20Z &metadataPrefix=oai_dc</requestURL> <record> <header> <identifier>oai:perseus:Perseus:text:1999.02.0084</identifier> <datestamp>2002-05-01T14:16:12Z</datestamp> </header> <metadata> <oai_dc:dc xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc/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> </oai_dc:dc> </metadata> </record> <record> <header> <identifier>oai:perseus:Perseus:text:1999.02.0083</identifier> <datestamp>2002-05-01T14:20:55Z</datestamp> </header> <metadata> <oai_dc:dc xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc/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> </oai_dc: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/provenance/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> |
http://memory.loc.gov/cgi-bin/oai? verb=ListRecords&from=2002-06-01T02:00Z&until=2002-06-01T03:00Z&metadataPrefix=oai_marc
<?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> |
This verb is used to retrieve the set structure of a repository.
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-21</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-9_!'$\(\)\+\-\.\*]+)*"/> </restriction> </simpleType> <complexType name="setDescriptionType"> <sequence> <any namespace="##other" processContents="lax"/> </sequence> </complexType> <!-- define resumptionToken - with 3 optional attributes --> <element name="resumptionToken"> <complexType> <simpleContent> <extension base="string"> <attribute name="expirationDate" type="oai:UTCdatetimeType" use="optional"/> <attribute name="completeListSize" type="positiveInteger" use="optional"/> <attribute name="cursor" type="nonNegativeInteger" use="optional"/> </extension> </simpleContent> </complexType> </element> </schema> |
This Schema is available at http://www.openarchives.org/OAI/2.0/OAI_ListSets.xsd |
http://an.oa.org/OAI-script? verb=ListSets
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). The subsets identified by setSpec 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> <oai_dc:dc xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc/oai_dc.xsd"> <dc:description>This set contains metadata describing electronic music recordings made during the 1950ies</dc:description> </oai_dc:dc> </setDescription> </set> <set> <setSpec>video</setSpec> <setName>Video Collection</setName> </set> </ListSets> |
http://purl.org/alcme/etdcat/servlet/OAIHandler? verb=ListSets
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> |
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 |
<schema targetNamespace="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <annotation> <documentation> XML Schema 2002-03-18 by Pete Johnston. Adjusted for usage in the OAI-PMH by Herbert Van de Sompel. Schema imports the Dublin Core elements from the DCMI schema for unqualified Dublin Core. </documentation> </annotation> <import namespace="http://purl.org/dc/elements/1.1/" schemaLocation="http://www.ukoln.ac.uk/metadata/dcmi/dcxml/xmls/simpled2.xsd"/> <element name="dc" type="oai_dc:oai_dcType"/> <complexType name="oai_dcType"> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="dc:title" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:creator" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:subject" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:description" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:publisher" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:contributor" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:date" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:type" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:format" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:identifier" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:source" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:language" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:relation" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:coverage" minOccurs="0" maxOccurs="unbounded"/> <element ref="dc:rights" minOccurs="0" maxOccurs="unbounded"/> </choice> </complexType> </schema> |
This Schema is available at http://www.openarchives.org/OAI/2.0/oai_dc/oai_dc.xsd |
<?xml version="1.0" encoding="UTF-8"?> <oai_dc:dc xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc/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> </oai_dc:dc> |
<?xml version="1.0" encoding="UTF-8"?> <oai_dc:dc xmlns:oai="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc/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> </oai_dc:dc> |
Support for the development of the OAI-PMH and for other Open Archives Initiative activities comes from the Digital Library Federation, the Coalition for Networked Information, and from the National Science Foundation through Grant No. IIS-9817416.
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 & University of Bath |
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 |
Many thanks to all involved in alpha-testing of version 2.0 of the OAI-PMH: Alan Kent <ajk@mds.rmit.edu.au> ; Xiaoming Liu <liu_x@cs.odu.edu> ;
Special thanks to Pete Johnston <p.johnston@ukoln.ac.uk> and Andy Powell <a.powell@ukoln.ac.uk> for work on Dublin Core schema.
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.
2002-03-30: Release of alpha two version of OAI-PMH version 2.0
2002-03-01: Release of alpha version of OAI-PMH version 2.0