Implementation Guidelines for the Open Archives Initiative Protocol for Metadata Harvesting

- XML schema to hold gateway descriptions

Protocol Version 2.0 of 2002-06-14
Document Version 2002/11/17T16:07:00Z
http://www.openarchives.org/OAI/2.0/guidelines-gateway.htm

alpha release. do not distribute.

Editors

The OAI Executive:
Carl Lagoze <lagoze@cs.cornell.edu> -- Cornell University - Computer Science
Herbert Van de Sompel <herbertv@lanl.gov> -- Los Alamos National Laboratory - Research Library

From the OAI Technical Committee:
Michael Nelson <mln@cs.odu.edu> -- Old Dominion University - Department of Computer Science
Simeon Warner <simeon@cs.cornell.edu> -- Cornell University - Computer Science

This document is one part of the Implementation Guidelines that accompany the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH).

1. Introduction

The gateway container is used to provide information about a gateway implementation. A gateway is a service that allows OAI-PMH access to repositories that are ordinarily accessible only through other protocols (e.g., Z39.50, Dienst). The gateway container allows the gateway to describe itself while not compromising the semantics of the OAI-PMH elements in an Identify response. The container may be used within a description block in the Identify response. The inclusion of this information does not guarantee that any service provider will choose to use it. The gateway information is contained in a single gateway container; a gateway must not embed more than one gateway container in an Identify response.

2. The `gateway` container

This gateway container consists of XML elements that allow for the description of the gateway itself; the XML elements do not describe the OAI-PMH interface provided by the gateway.

The gateway container must include one instance of each of the following elements:

source - The URI of the remote source data that the gateway is making harvestable via the OAI-PMH.
gatewayDescription - A formal description of the gateway or the network-location of such a formal description.
gatewayURL - The network-location of the gateway itself. This is the "prefix" shared by all OAI-PMH repositories accessible through the gateway. If two repositories share this prefix, they can be assumed to be using the same gateway.

The gateway container must include one or more instance of the following element:

gatewayAdmin - The email address of a person responsible for maintaining the gateway.

The gateway container may include one instance of the following element:

gatewayNotes - Additional notes about the particular instantiation of the gateway, or the network-location of such notes. This element could be used to described usage policies, software versions, and related information.

gateway description container

<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://www.openarchives.org/OAI/2.0/gateway/"
  xmlns="http://www.w3.org/2001/XMLSchema" 
  xmlns:oai="http://www.openarchives.org/OAI/2.0/"
  xmlns:gateway="http://www.openarchives.org/OAI/2.0/gateway/" 
  elementFormDefault="qualified" attributeFormDefault="unqualified">

  <import  namespace="http://www.openarchives.org/OAI/2.0/" 
        schemaLocation="http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd"/>

  <annotation>
    <documentation>
      Schema for gateways between OAI-PMH and other protocols / formats
      Validated at http://www.w3.org/2001/03/webdata/xsv 2002/11/17 19:10:04
	by MLN
    </documentation>
  </annotation>

  <element name="gateway">
    <complexType>
      <sequence>
        <element name="source" type="string"/>
        <element name="gatewayDescription" 
                 type="gateway:TextURLType"/>
        <element name="gatewayURL" type="anyURI"/>
        <element name="gatewayAdmin" maxOccurs="unbounded" 
                 type="oai:emailType"/>
        <element name="gatewayNotes" minOccurs="0"
                 type="TextURLType"/>
      </sequence>
    </complexType>
  </element>

<complexType name="TextURLType" > 
   <choice minOccurs="0" maxOccurs="unbounded">
     <element name="URL" minOccurs="0" maxOccurs="unbounded" type="anyURI"/>
     <element name="text" minOccurs="0" maxOccurs="unbounded" type="string"/>
   </choice>
 </complexType>

</schema>

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

3. Examples

The following example shows a gateway container returned in a description block in the response to an Identify request issued against a gateway that converts between the Dienst protocol and the OAI-PMH.

<gateway xmlns="http://www.openarchives.org/OAI/2.0/gateway/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/gateway/
                      http://www.openarchives.org/OAI/2.0/gateway.xsd">
    <source>http://foo.edu/Dienst/</source>
    <gatewayDescription>
       <URL>http://cs-tr.cs.cornell.edu/Dienst/UI/2.0/Describe/ncstrl.cornell/TR94-1418</URL>
    </gatewayDescription>
    <gatewayURL>http://bar.edu/oai-gateway/2.0/</gatewayURL>
    <gatewayAdmin>admin@bar.edu</gatewayAdmin>
    <gatewayAdmin>admin-alternative@bar.edu</gatewayAdmin>
    <gatewayNotes>
       <URL>http://bar.edu/oai-gateway/notes.html</URL>
    </gatewayNotes>
</gateway>

The following example shows a gateway container returned in a description block in the response to an Identify request issued against a gateway that converts between the Static Repository Format and the OAI-PMH.

<gateway xmlns="http://www.openarchives.org/OAI/2.0/gateway/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/gateway/
                      http://www.openarchives.org/OAI/2.0/gateway.xsd">
    <source>http://an.oai.org/ma/mini.xml</source>
    <gatewayDescription>
       <URL>http://www.openarchives.org/OAI/2.0/guidelines-static-repository.htm</URL>
    </gatewayDescription>
    <gatewayURL>http://bar.edu/oai-gateway/2.0/</gatewayURL>
    <gatewayAdmin>pat@institution.org</gatewayAdmin>
    <gatewayNotes>
       <URL>http://gateway.institution.org/oai/</URL>
    </gatewayNotes>
</gateway>

Acknowledgements

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. Individuals who have played a significant role in the development of OAI-PMH version 2.0 are acknowledged in the protocol document.

Document History

2003-10-07: Third version of this document.

2002-11-08: Second version of this document.

2002-11-08: First version of this document.