Repository

A repository is administratively divided into a set of partitions. Each partition stores documents, as defined by the Dienst document model, and provides messages to deposit documents, discover their structure, and obtain disseminations of documents. A number of dissemination variables effect the nature of a particular dissemination request. For more on the Repository Service, please see: http://www.cs.cornell.edu/cdlrg/dienst/protocols/DienstProtocol.htm#4.1%20Repository%20Service

 Describe Verb Describe-Verb 2.0 req value none text/xml 200, 400

Returns a structured response that contains a list, where each element of the list provides information on a version of the specified verb that is supported by this service. The following information may be provided at the verb or version level.

  • description, description of the verb or a specific version
  • note, information pertaining to the verb or a specific version

Each element of the list contains the following information:

  • version number of the verb.
  • arguments, a list of the names of the fixed and keyword arguments, if any, accepted by the verb in that version.
  • example template of request to this repository, with fixed argument indicated in brackets
  • returns, optional, contains information about response format.

Note that a service may implement more than one version of a verb.

 Protocol=dienst;Service=Repository;ver=2.0;verb=Describe-Verb;value=Formats <?xml version="1.0" encoding="UTF-8"?> <Describe-Verb version="2.0"> <Verb name="Formats"> <description>Returns a structured response indicating the formats of disseminations available for this document </description> <versions> <version id="4.0"> <example>http://www.umdl.umich.edu/cgi/b/broker/broker?Protocol=dienst;Service=Repository;ver=2.0;verb=Formats;handle=handlevalue></example> <arguments> <fixed> <arg name="handle" /> </fixed> <keyword> <arg name="version" /> <arg name="view" /> </keyword> </arguments> </version> <version id="2.0"> <note>Depricated</note> <example>http://cs-tr.cs.cornell.edu:80/Dienst/Repository/2.0/Formats/<handle></example> <arguments> <fixed> <arg name="handle" /> </fixed> </arguments> </version> </versions> </Verb> </Describe-Verb> Disseminate Content Disseminate 1.0 mod Our tentative position on this is that the record-oriented components are to be replaced by OAI verb GetRecord, and that this Dienst verb needs to continue for handling the actual content. handle, view, content-type version, <div>, pageimage, binder, encoding dependent on dissemination requested. 200, 400, 404, 415, 501, 503

Request a dissemination of a digital object. The characteristics of the dissemination that can be requested (the arguments to the Disseminate verb), are determined by the responses to the List-Versions, Formats, and Structure verbs for the specific digital object. The response is a MIME-typed byte stream. The MIME type of the byte stream is either the MIME type of the specified content-type or, if a binder is specified, the MIME type of that binder. Refer to the examples below for more information on the stream that is returned.

In addition to the handle, the required fixed arguments are:

  • view specifies the view of the document instance from which a dissemination is requested. This argument takes one of three forms:
    • #<meta-format> ,where <meta-format> is one of the metadata formats (as returned from the ListMetadataFormats request). The resulting dissemination is then the top-level (document instance) metadata records in the requested format. For example, #rfc1807 requests the rfc1807 metadata record for the document instance.
    • <viewID>#<meta-format> ,where <viewID> is one of the metadata formats (as returned from the ListMetadataFormats request). The resulting dissemination is then the view specific metadata records in the requested format. For example, view=body#rfc1807 requests the rfc1807 metadata record for the body view of the document instance.
    • <viewID>,where <viewID> is one of the available views for the document instance. The resulting dissemination, if there is no pageimage argument, is then the specified view of the document instance.
  • content-type is a required argument that specifies the MIME-type of the content in the dissemination. The list of available content-types for a document instance is indicated by the response to the Formats request. Note that the value supplied for the argument is not the actual MIME-type, but the tag for that MIME type as indicated in the response to the Formats request (because of the complications with the "/" character in HTTP requests). For metadata requests, the only content-type that is supported is xml. If there is no binder argument, then this is the MIME-type of the stream disseminated to the client.

The Keyword Arguments are:

  • version specifies the document instance from which a dissemination is requested. If omitted, the latest document instance is used by default.
  • <div> narrows the dissemination request to a specific structural component (e.g., a chapter) of the specified view of the document instance. The supplied argument must be one the available divs of the view (indicated by the output of the Structure request) paired with a value that is an identifier of one of those divs (again indicated by the output of the Structure request). For example, if a Structure request indicates that there is a div of type chapter with identifier 1, then this argument could by chapter=1. Note that the div argument can not be used in combination with the pageimage argument.
  • pageimage narrows the dissemination request to a specific page of the specified view of the document instance. The value must be an identifier of one the available pages of the view (indicated by the output of the Structure request).
  • binder specifies the encapsulating binder for the dissemination. The MIME type of the stream disseminated to the requesting client is then the output of the binder application. A binder argument is required if the dissemination contains multiple logical objects (e.g., multiple page images in image/tiff). The list of Binders supported by a repository is available through the List-Binders protocol request.
  • encoding specifies the compression encoding scheme that should be applied to the dissemination. The encoding applied is reflected in the HTTP Content-encoding header returned from the Disseminate request. The list of Encodings supported by a repository is available through the List-Encodings protocol request.
Protocol=Dienst;Service=Repository;verb=Disseminate;ver=1.0;handle=handlecorp/970101;view=body;content-type=postscript The PostScript rendition (MIME-type postscript) of "body" view of the document. Protocol=Dienst;Service=Repository;verb=Disseminate;ver=1.0;handle=handlecorp/970101;content-type=oams/xml The Open Archives metadata record for the document instance (in the only available content-type for metadata which is xml). <?xml version="1.0" encoding="UTF-8"?> <Disseminate version="1.0"> <oams:oams xmlns:oams="http://www.openarchives.org/sfc/sfc_oams.htm"> <oams:title>A protocol for Interoperable Archives</oams:title> <oams:accession date="1994-06-24 /> <oams:fullId>ncstrl.cornell/TR94-1418</oams:fullId> <oams:author> <oams:name>James R. Davis</oams:name> <oams:organization>Xerox</oams:organization> </oams:author> <oams:author> <oams:name>Carl Lagoze</oams:name> <oams:organization>Cornell</oams:organization> </oams:author> </oams:oams> </Disseminate> Protocol=Dienst;Service=Repository;verb=Disseminate;ver=1.0;handle=handlecorp/970101;view=book;content-type=gif;pageimage=3 Page 3 of the book view of the document instance as a GIF file (MIME type image/gif). Protocol=Dienst;Service=Repository;verb=Disseminate;ver=1.0;handle=handlecorp/970101;view=book;content-type=gif;chapter=3&binder=tar&encoding=gzip Chapter of the book view of the document instance as a series of GIF files, bound together using tar, and then compressed using gzip. The MIME type of the disseminated byte stream is than application/tar. List Formats Formats 4.0 dep Subsumed in modification of the verb Structure. We also agreed that Formats was inadequate and needed to be tied more closely to Structure. See also the discussion regarding Structure. handle version, view text/xml 200, 400, 404, 501

Returns a structured response indicating the formats of disseminations available for this document instance.

The available arguments are:

  • version specifies the document instance for which the format information is requested. If omitted, it provides information about the latest document instance.
  • view specifies the view of the document instance for which format information is requested. If omitted, it provides information about the entire document instance.

The response includes the following information:

  • a list of content-types with the following information for each content type:
    • tag, which is the string that can be used in a Disseminate request.
    • MIME-type, which is the corresponding MIME type of this tag.
    • size, an estimate of the number of bytes of the dissemination, expressed in that content-type. This is returned only if the size can be determined.
    • URL, an alternative URL (if available) that can be used to download the document instance in this content-type. This is intended for sites wish to offer a "backdoor" to the Dienst protocol for retrieving the respective representation of the document. Note that this alternative URL will not allow the functionality of the Dienst Disseminate request, such as version selection, part selection, and the like
Protocol=Dienst;Service=Repository;verb=Formats;ver=4.0;handle=handlecorp/970101?version=1&part=body <?xml version="1.0" encoding="UTF-8"?> <Formats version="4.0"> <formats> <postscript name="application/postscript" size="25555" URL="http://foo.com/bar.ps" /> <gif name="image/gif" /> </formats> </Formats> Get Records GetRecord 1.0 req This OAI verb is introduced into the NSF/DFG project to bring our version of the protocol into compliance with OAI. It replaces the record-oriented parts of the verb Disseminate. none identifier, metadataPrefix text/xml

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

The arguments are used as follows:

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

Exception conditions include:

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

For more information on this verb, please see: http://www.openarchives.org/OAI/openarchivesprotocol.htm#GetRecord.

 Request a record in the Dublin Core metadata format [URL shown without encoding for better readibility]. http://an.oa.org/OAI-script?verb=GetRecord&identifier=oai:arXiv:quant-ph/9901001&metadataPrefix=oai_dc <?xml version="1.0" encoding="UTF-8"?> <GetRecord xmlns="http://www.openarchives.org/OAI/1.0/OAI_GetRecord" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_GetRecord http://www.openarchives.org/OAI/1.0/OAI_GetRecord.xsd"> <responseDate>2000-10-10T14:09:57-07:00</responseDate> <requestURL>http://an.oa.org/OAI-script?verb=GetRecord &identifier=oai%3AarXiv%3Aquant-ph%2F9901001 &metadataPrefix=oai_dc</requestURL> <record> <header> <identifier>oai:arXiv:quant-ph/9901001</identifier> <datestamp>1999-01-01</datestamp> </header> <metadata> <dc xmlns="http://purl.org/dc/elements/1.1/" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://purl.org/dc/elements/1.1/ http://www.openarchives.org/OAI/dc.xsd"> <title>Quantum slow motion</title> <creator>Hug, M.</creator> <creator>Milburn, G. J.</creator> <description>We simulate the center of mass motion of cold atoms in a standing, amplitude modulated, laser field as an example of a system that has a classical mixed phase-space.</description> <date>1999-01-01</date> <type>e-print</type> <identifier>http://arXiv.org/abs/quant-ph/9901001</identifier> </dc> </metadata> </record> </GetRecord> Request a record in the Dublin Core metadata format. The requested record, however, can not be returned because the identifier does not exist. Therefore, the response does not contain a record container [URL shown without encoding for better readibility]. http://an.oa.org/OAI-script?verb=GetRecord&identifier=oai:arXiv:quant-ph/0201001&metadataPrefix=oai_dc <?xml version="1.0" encoding="UTF-8"?> <GetRecord xmlns="http://www.openarchives.org/OAI/1.0/OAI_GetRecord" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_GetRecord http://www.openarchives.org/OAI/1.0/OAI_GetRecord.xsd"> <responseDate>2000-10-10T14:09:57-07:00</responseDate> <requestURL>http://an.oa.org/OAI-script?verb=GetRecord &identifier=oai%3AarXiv%3Aquant-ph%2F0201001 &metadataPrefix=oai_dc</requestURL> </GetRecord> Request a record in the oai_marc metadata format. However, the requested metadata format can not be disseminated for this identifier. Therefore, the response record contains a header but no metadata container [URL shown without encoding for better readibility].http://an.oa.org/OAI-script?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/1.0/OAI_GetRecord" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_GetRecord http://www.openarchives.org/OAI/1.0/OAI_GetRecord.xsd"> <responseDate>2000-10-10T14:09:57-07:00</responseDate> <requestURL>http://an.oa.org/OAI-script?verb=GetRecord &identifier=oai%3AarXiv%3Aquant-ph%2F9901001 &metadataPrefix=oai_marc</requestURL> <record> <header> <identifier>oai:arXiv:quant-ph/9901001</identifier> <datestamp>1999-01-01</datestamp> </header> </record> </GetRecord> List Authorities List-Authorities 1.0 req none none text/xml 200, 400

Return a structured list of the authorities stored in this repository.

 Protocol=Dienst;Service=Repository;verb=List-Authorities;ver=1.0 <?xml version="1.0" encoding="UTF-8"?> <List-Authorities version="1.0"> <authority> <name>ncstrl.cornell</name> <display>Cornell University Computer Science Department</display> </authority> </List-Authorities> List Binders List-Binders 1.0 req none none text/xml 200, 400

Return a structured list of the types of binders available in this repository.

 Protocol=Dienst;Service=Repository;verb=List-Binders;ver=1.0 <?xml version="1.0" encoding="UTF-8"?> <List-Binders version="1.0"> <binder>tar</binder> </List-Binders> List Contents List-Contents 4.0 rep This is replaced by the OAI verbs ListIdentifiers and ListRecords. none partitionspec, file-after, file-before, meta-format text/xml 200, 400, 501

Return a structured list of the handles for documents stored in this repository service. Without any arguments the list includes all stored documents.

The meaning of the Keyword Arguments is as follows:

  • file-after limits the list to those handles for documents that were added or modified since time, a universal time expressed in ISO 8601 format. If the server is not able to determine date of modification to the resolution of a day, or if the server is not able to selectively extract records on a time scale of a day, the server may return additional records, e.g. all those modified during the week, month, or even century containing the date.
  • file-before limits the list to those handles for documents that were added or modified prior to time, a universal time expressed in ISO 8601 format. If the server is not able to determine date of modification to the resolution of a day, or if the server is not able to selectively extract records on a time scale of a day, the server may return additional records, e.g. all those modified during the week, month, or even century containing the date.
  • partitionpsec limits the returned handles to those in the specified partition specification. The partitions available for a repository are returned from the List-Partitions request..
  • meta-format returns, in addition to the handle, metadata for each document in the specified format. The metadata is empty for any document that does not have metadata in that format. Legal values for this argument is one of the metadata formats (as returned from the ListMetadataFormats request).
List the handles in the high energy (hep) partition within the physics partition.Protocol=Dienst;Service=Repository;verb=List-Contents;ver=4.0;partitionspec=physics;hep <?xml version="1.0" encoding="UTF-8"?> <List-Contents version="4.0"> <record> handlecorp/970101 </record> <record> handlecorp/970102 </record> </List-Contents> List the rfc1807 metadata along with the handlesProtocol=Dienst;Service=Repository;verb=List-Contents;ver=4.0;partitionspec=physics;hep&meta-format=rfc1807 Note the empty rfc1807 record for handlecorp/970102 indicating that there is no rfc1807 metadata for this document. <?xml version="1.0" encoding="UTF-8"?> <List-Contents version="4.0"> <record> handlecorp/970101 <rfc1807:rfc1807 xmlns:rfc1807="ftp://nic.merit.edu/document/rfc/rfc1807.txt"> <rfc1807:author>William Shakespeare</rfc1807:author> <rfc1807:title>Romeo and Juliet</rfc1807:title> <rfc1807:id>handlecorp//970101</rfc1807:id> <rfc1807:entry>June 24 1506</rfc1807:entry> </rfc1807:rfc1807> </record> <record> handlecorp/970102 <rfc1807:rfc1807 xmlns:rfc1807="ftp://nic.merit.edu/document/rfc/rfc1807.txt"> > </rfc1807:rfc1807> </record> </List-Contents> List Identifiers ListIdentifiers 1.0 req This OAI verb is introduced into the NSF/DFG project to bring our version of the protocol into compliance with OAI. Along with ListRecords, it replaces the Dienst verb List-Contents. Please note: the resumptionToken is not implemented at Michigan. none until, from, set, resumptionToken text/xml

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

The arguments are used as follows:

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

Exception Conditions include: No records match the request - The response will not contain any identifier elements.

For more information on this verb, please see: http://www.openarchives.org/OAI/openarchivesprotocol.htm#ListIdentifers.

 List the unique identifiers of records added or modified since January 15, 1998 in the "hep" Set of the "physics" Set [URL shown without encoding for better readibility].http://an.oa.org/OAI-script?verb=ListIdentifiers&from=1998-01-15&set=physics:hep A list of four identifiers is returned, one of which has a "deleted" status. In addition, a resumption token has been returned, indicating the list of identifiers is incomplete and one or more subsequent requests will need to be issued to complete the list. <?xml version="1.0" encoding="UTF-8"?> <ListIdentifiers xmlns="http://www.openarchives.org/OAI/1.0/OAI_ListIdentifiers" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_ListIdentifiers http://www.openarchives.org/OAI/1.0/OAI_ListIdentifiers.xsd"> <responseDate>2000-10-01T19:20:30-04:00</responseDate> <requestURL>http://an.oa.org/OAI-script?verb=ListIdentifiers &from=1998-01-15&setSpec=physics%3Ahep</requestURL> <identifier>oai:arXiv:hep-th/9801001</identifier> <identifier>oai:arXiv:hep-th/9801002</identifier> <identifier>oai:arXiv:hep-th/9801005</identifier> <identifier status="deleted">oai:arXiv:hep-th/9801010</identifier> <resumptionToken>xxx45abttyz</resumptionToken> </ListIdentifiers> Issue a subsequent request to the one issued above, with a single resumptionToken argument whose value is that returned in the previous response.http://an.oa.org/OAI-script?verb=ListIdentifiers&resumptionToken=xxx45abttyz <?xml version="1.0" encoding="UTF-8"?> <ListIdentifiers xmlns="http://www.openarchives.org/OAI/1.0/OAI_ListIdentifiers" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_ListIdentifiers http://www.openarchives.org/OAI/1.0/OAI_ListIdentifiers.xsd"> <responseDate>2000-10-01T19:20:30-04:00</responseDate> <requestURL>http://an.oa.org/OAI- script?verb=ListIdentifiers &resumptionToken=xxx45abttyz</requestURL> <identifier>oai:arXiv:hep-th/9801020</identifier> <identifier>oai:arXiv:hep-th/9801060</identifier> </ListIdentifiers> List the unique identifiers of records added or modified on January 1, 2001 in the "hep" Set of the "physics" Set. There are no matches for this request, hence, the response does not contain any identifier tags [URL shown without encoding for better readibility].http://an.oa.org/OAI-script?verb=ListIdentifiers&from=2001-01-01&until=2001-01-01&set=physics:hep <?xml version="1.0" encoding="UTF-8"?> <ListIdentifiers xmlns="http://www.openarchives.org/OAI/1.0/OAI_ListIdentifiers" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_ListIdentifiers http://www.openarchives.org/OAI/1.0/OAI_ListIdentifiers.xsd"> <responseDate>2000-10-01T19:20:30-04:00</responseDate> <requestURL>http://an.oa.org/OAI-script?verb=ListIdentifiers &from=2001-01-01&until=2001-01-01 &setSpec=physics%3Ahep</requestURL> </ListIdentifiers> List Encodings List-Encodings 1.0 req none none text/xml 200, 400

Return a structured list of the types of encodings available in this repository.

 Protocol=Dienst;Service=Repository;verb=List-Encodings;ver=1.0 <?xml version="1.0" encoding="UTF-8"?> <List-Encodings version="1.0"> <Encoding>gzip</Encoding> </List-Encodings> Get Metadata Formats List-Meta-Formats 1.0 rep Replaced by OAI verb ListMetadataFormats. none none text/xml 200, 400, 501

Returns a structured response indicated the metadata formats that are supported by this repository service. Note that the fact that a metadata format is supported does not mean that it is available for all digital objects in that repository. For each metadata format, the following information is returned:

  • The name, which is the identifier for the metadata format that can be used in other Dienst protocol requests.
  • The namespace ID, which is a URL that refers to a document describing the metadata format.
/Dienst/Repository/1.0/List-Meta-Formats <?xml version="1.0" encoding="UTF-8"?> <List-Meta-Formats version="1.0"> <meta-format name="rfc1807" namespace="ftp://nic.merit.edu/document/rfc/rfc1807.txt" /> <meta-format name="dc" namespace="http://purl.org/dc" /> </List-Meta-Formats> List Metadata Formats ListMetadataFormats 1.0 req This OAI verb is introduced into the NSF/DFG project to bring our version of the protocol into compliance with OAI. It replaces the Dienst verb List-Meta-Formats. In my notes from the meeting, I wrote "need agreement on name values" (jpw). none identifier text/xml

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.

The arguments are used as follows:

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

Exception Conditions include: No records match the request - The response will not contain a metadataFormat container.

For more information on this verb, please see: http://www.openarchives.org/OAI/openarchivesprotocol.htm#ListMetadataFormats.

 List the metadata formats that can be disseminated from the record with unique identifier oai:arXiv:hep-th/9901001 [URL shown without encoding for better readibility]. http://an.oa.org/OAI-script?verb=ListMetadataFormats&identifier=oai:arXiv:hep-th/9901001 <?xml version="1.0" encoding="UTF-8"?> <ListMetadataFormats xmlns="http://www.openarchives.org/OAI/1.0/OAI_ListMetadataFormats" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_ListMetadataFormats http://www.openarchives.org/OAI/1.0/OAI_ListMetadataFormats.xsd"> <responseDate>2000-10-01T19:20:30-04:00</responseDate> <requestURL>http://an.oa.org/OAI-script?verb=ListMetadataFormats &identifier=oai%3AarXiv%3Ahep-th%2F9901001</requestURL> <metadataFormat> <metadataPrefix>oai_rfc1807</metadataPrefix> <schema>http://www.openarchives.org/OAI/rfc1807.xsd</schema> </metadataFormat> <metadataFormat> <metadataPrefix>oai_dc</metadataPrefix> <schema>http://www.openarchives.org/OAI/dc.xsd</schema> <metadataNamespace>http://purl.org/dc/elements/1.1/</metadataNamespace> </metadataFormat> </ListMetadataFormats> List the metadata formats that can be disseminated from the repository http://an.oa.org/OAI-script.http://an.oa.org/OAI-script?verb=ListMetadataFormats <?xml version="1.0" encoding="UTF-8"?> <ListMetadataFormats xmlns="http://www.openarchives.org/OAI/1.0/OAI_ListMetadataFormats" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_ListMetadataFormats http://www.openarchives.org/OAI/1.0/OAI_ListMetadataFormats.xsd"> <responseDate>2000-10-01T19:20:30-04:00</responseDate> <requestURL>http://an.oa.org/OAI-script?verb=ListMetadataFormats</requestURL> <metadataFormat> <metadataPrefix>oai_rfc1807</metadataPrefix> <schema>http://www.openarchives.org/OAI/rfc1807.xsd</schema> </metadataFormat> <metadataFormat> <metadataPrefix>oai_dc</metadataPrefix> <schema>http://www.openarchives.org/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/oai_marc.xsd</schema> </metadataFormat> </ListMetadataFormats> List the metadata formats that can be disseminated from the record with unique identifier oai:arXiv:hep-th/0101001. The identifier, however, does not exist and therefore, the response does not contain a metadataFormat container. [URL shown without encoding for better readibility].http://an.oa.org/OAI-script?verb=ListMetadataFormats&identifier=oai:arXiv:hep-th/0101001 <?xml version="1.0" encoding="UTF-8"?> <ListMetadataFormats xmlns="http://www.openarchives.org/OAI/1.0/OAI_ListMetadataFormats" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_ListMetadataFormats http://www.openarchives.org/OAI/1.0/OAI_ListMetadataFormats.xsd"> <responseDate>2000-10-01T19:20:30-04:00</responseDate> <requestURL>http://an.oa.org/OAI-script?verb=ListMetadataFormats &identifier=oai%3AarXiv%3Ahep-th%2F0101001</requestURL> </ListMetadataFormats> List Partitions List-Partitions 2.0 rep Replaced by OAI verb ListSets none none text/xml 200, 400, 501

Return a structured list of the administrator-determined partitions for documents stored in this repository service. The list contains the hierarchy of partitions and sub-partitions. For each partition, both the short name and long description is returned.

 /Dienst/Repository/2.0/List-Partitions The following response indicates a partition hierarchy with two top level partitions - Oceanside and ValleyView - each with partitions hierarchies within them. <?xml version="1.0" encoding="UTF-8"?> <List-Partitions version="2.0"> <partition name="Oceanside"> <display>Oceanside University of Nebraska</display> <partition name="CompEnt"> <display>Department of Computational Entomology</display> </partition> <partition name="MetPhen"> <display>Department of Metaphysical Phenomenology</display> </partition> </partition> <partition name="ValleyView"> <display>Valley View University of Florida</display> <partition name="Fren"> <display>Department of Frenetics</display> </partition> <partition name="Hist"> <display>Department of Histrionics</display> </partition> </partition> </List-Partitions> This example shows the nested partition lay out described earlier. List Records ListRecords 1.0 req This OAI verb is introduced into the NSF/DFG project to bring our version of the protocol into compliance with OAI. Along with ListIdentifiers, replaces the Dienst verb List-Contents. none until, from, set, resumptionToken, metadataPrefix text/xml

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

The arguments are used as follows:

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

Exception conditions include:

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

For more information on this verb, please see: http://www.openarchives.org/OAI/openarchivesprotocol.htm#ListRecords.

 List the records in rfc1807 format added or modified since January 15, 1998 in the "hep" set of the "physics" set [URL shown without encoding for better readibility].http://an.oa.org/OAI-script?verb=ListRecords&from=1998-01-15&set=physics:hep&metadataPrefix=oai_rfc1807

Three records are returned:

  • The first includes the rfc1807 metadata. This record also has an "about" part.
  • The second only has a header without the rfc1807 metadata container because the metadata for that record can not be expressed in rfc1807 format.
  • The third has a status="deleted" attribute (and therefore no metadata part).
<?xml version="1.0" encoding="UTF-8"?> <ListRecords xmlns="http://www.openarchives.org/OAI/1.0/OAI_ListRecords" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_ListRecords http://www.openarchives.org/OAI/1.0/OAI_ListRecords.xsd"> <responseDate>2000-10-01T19:20:30-04:00</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> </header> <metadata> <rfc1807 xmlns="http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1807.txt" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation= "http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1807.txt http://www.openarchives.org/OAI/rfc1807.xsd"> <bib-version>v2</bib-version> <id>hep-th/9901001</id> <entry>January 1, 1999</entry> <title>Investigations of Radioactivity</title> <author>Ernest Rutherford</author> <date>March 30, 1999</date> </rfc1807> </metadata> <about> <dc xmlns="http://purl.org/dc/elements/1.1/" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://purl.org/dc/elements/1.1/ http://www.openarchives.org/OAI/dc.xsd"> <publisher>Los Alamos arXiv</publisher> <rights>Metadata may be used without restrictions as long as the oai identifier remains attached to it.</rights> </dc> </about> </record> <record> <header> <identifier>oai:arXiv:hep-th/9901004</identifier> <datestamp>1999-12-26</datestamp> </header> </record> <record status="deleted"> <header> <identifier>oai:arXiv:hep-th/9901007</identifier> <datestamp>1999-12-21</datestamp> </header> </record> </ListRecords> List Sets ListSets 1.0 req This OAI verb is introduced into the NSF/DFG project to bring our version of the protocol into compliance with OAI. It replaces the Dienst verb List-Partitions. none resumptionToken text/xml

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

The arguments are used as follows:

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

Exception conditions include: Repository contains no set hierarchy - The response will not contain any set containers.

For more information on this verb, please see: http://www.openarchives.org/OAI/openarchivesprotocol.htm#ListSets.

 http://an.oa.org/OAI-script?verb=ListSets The following response indicates a set hierarchy with two top level sets - Oceanside and ValleyView - each with two sets within them. <?xml version="1.0" encoding="UTF-8"?> <ListSets xmlns="http://www.openarchives.org/OAI/1.0/OAI_ListSets" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_ListSets http://www.openarchives.org/OAI/1.0/OAI_ListSets.xsd"> <responseDate>2000-10-01T19:20:30-04:00</responseDate> <requestURL>http://an.oa.org/OAI-script?verb=ListSets</requestURL> <set> <setSpec>Oceanside</setSpec> <setName>Oceanside University of Nebraska</setName> </set> <set> <setSpec>Oceanside:CompEnt</setSpec> <setName>Department of Computational Entomology</setName> </set> <set> <setSpec>Oceanside:MetPhen</setSpec> <setName>Department of Metaphysical Phenomenology</setName> </set> <set> <setSpec>ValleyView</setSpec> <setName>Valley View University of Florida</setName> </set> <set> <setSpec>ValleyView:Fren</setSpec> <setName>Department of Frenetics</setName> </set> <set> <setSpec>ValleyView:Hist</setSpec> <setName>Department of Histrionics</setName> </set> </ListSets> http://another.oa.org/OAI-script?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/1.0/OAI_ListSets" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/1.0/OAI_ListSets http://www.openarchives.org/OAI/1.0/OAI_ListSets.xsd"> <responseDate>2000-10-01T19:20:30-04:00</responseDate> <requestURL>http://another.oa.org/OAI-script?verb=ListSets</requestURL> </ListSets> List Verbs List-Verbs 2.0 req none none text/xml 200, 400

Returns a structured response containing the name of the verbs defined by this service.

 Protocol=Dienst;Service=Repository;verb=List-Verbs;ver=2.0 <?xml version="1.0" encoding="UTF-8"?> <List-Verbs version="2.0"> <verb>Disseminate</verb> <verb>Formats</verb> <verb>List-Contents</verb> <verb>List-Verbs</verb> </List-Verbs> List Document Versions List-Versions 1.0 req handle none text/xml 200, 400, 501

Returns a structured response describing the current versions (document instances) available for the requested handle. The information returned consists of:

id
is the version number, a positive integer
date
is the date the version was last modified, expressed as in ISO 8601, or * if this can’t be determined
comment
is a comment or description. It may not contain a newline.
Protocol=Dienst;Service=Repository;verb=List-Versions;ver=1.0;handle=handlecorp%2f970101 <?xml version="1.0" encoding="UTF-8"?> <List-Versions version="1.0"> <version id="2"> <date>1999-02-01</date> <comment>this version</comment> </version> <version id="1"> <date>1998-02-01</date> <comment>that version</comment> </version> </List-Versions> Submit a New Version of a Document New-Version 1.0 opt handle comment text/xml 200, 400, 401, 404, 501

Submit a new version of a document with identifier handle that is currently stored in the repository. The version number of the new version is then one greater than the previous most current version (and it becomes the default version for Disseminate and Structure requests are made without version arguments).

Note on Permissions: It is the responsibility of the repository service implementation to provide some level of access control over the versioning process. One common mechanism is for a repository service implementation to only accept New-Version requests from clients with specific DNS client identifiers. In this case the client is left with the responsibility that the party requesting a new version is authorized to do so.

This is transmitted as a HTTP POST request where the input stream is a MIME type multipart/mixed. This input stream has two parts ordered as follows:

  • an RFC1807 metadata file with MIME type text/x-rfc1807.
  • the content in one of the formats that this repository is capable of accepting as an input format. Refer to the Submit-Formats verb for the method of retrieving the input formats acceptable to a repository.

The meaning of the arguments is as follows:

  • comment - a free text description of the new version.

If the new version request is successful the structured return contains:

  • version # of the latest version.
  • date the version was submitted
  • comment for this version.
In addition an input stream should be supplied with the POST that includes this request.Protocol=Dienst;Service=Repository;verb=New-Version;ver=1.0;description=fixed+wrong+algorithm <?xml version="1.0" encoding="UTF-8"?> <New-Version version="1.0"> <version id="2"> <date>1999-02-01></date> <comment>fixed wrong algorithm</comment> </version> </New-Version> Get Document Structure Structure 2.0 mod For Structure, we discussed replacing the unnumbered DIVs, which can nest, with numbered DIVs (e.g., DIV1, DIV2, etc.). Further, Structure should use real ID values (i.e., only NAME characters, beginning with an alpha character), and need to have a sense of relationship between layers (e.g., what shows first, GIF or PDF?) and a repository's desire to suppress or hold back a layer (e.g., don't show the OCR without this caveat, or don't show it until you've shown other layers, and then only with this caveat). handle version, view, content-type text/xml 200, 400, 404, 415, 501, 503

This verb returns a structured response that describes the decompositions available for a document instance. A client may use the decomposition information as the basis for document requests using the Disseminate verb.

The meaning of the Keyword Arguments is as follows:

  • version specifies the document instance for which the structure information is requested. If omitted, it provides information about the latest document instance.
  • view specifies the view of the document instance for which structure information is requested. If omitted, it provides information about the entire document instance. The distinguished view # specifies that only the types of metadata available for the document instance should be returned.
  • content-type specifies a particular content type for which structure information is requested. If omitted, it provides information about all decompositions for all content-types.

The response lists the meta-formats, views, divs, and pageimages as described above.

 Protocol=Dienst;Service=Repository;verb=Structure;ver=2.0;handle=handlecorp/970101;version=1 <?xml version="1.0" encoding="UTF-8"?> <Structure version="2.0"> <meta-formats> <rfc1807 /> <dc /> </meta-formats> <view id="book"> <div id="section 1"> <div id="chapter 1"> <pageimage id="1"> <pageimage id="2"> <pageimage id="3"> </div> </div> </view> </Structure> This response says that the document instance can disseminate two metadata formats at the top level, rfc1807 and dc (Dublin Core). The document instance also has one disseminable view called body. This view is structured into a section and chapter hierarchy, with individually disseminable pages available at the chapter. (Note that additional sections and chapters have been omitted in the example for brevity). Protocol=Dienst;Service=Repository;verb=Structure;ver=2.0;handle=handlecorp/970101 <?xml version="1.0" encoding="UTF-8"?> <Structure version="2.0"> <meta-format> <rfc1807 /> </meta-format> <view id="body" divs="pageimage" min="1" max="150" /> </Structure> This is the "shorthand" response for documents with simple structure. The response indicates one metadata type for the document instance, rfc1807, and a single view, body, with a set of sequential pages numbered from 1 to 150 inclusive. Protocol=Dienst;Service=Repository;verb=Structure;ver=2.0;handle=handlecorp/970101;view=body <?xml version="1.0" encoding="UTF-8"?> <Structure version="2.0"> <view id="body" divs="pageimage" min="1" max="150" /> </Structure> This request, and the associated response, demonstrates the use of the view argument in the request, which specifies that structure information only for the specified view should be returned. /Dienst/Repository/2.0/Structure/handlecorp/970101?view=%23 This request specifies that only the metadata formats for the document should be returned. <?xml version="1.0" encoding="UTF-8"?> <Structure version="2.0"> <meta-format> <rfc1807 /> <dc /> </meta-format> </Structure> This response says that the document can disseminate two metadata formats rfc1807 and dc (Dublin Core). Submit a Document Submit 1.0 opt id, partitionspec, authority text/xml 200, 400, 401, 501

Submit a new document to be stored in the repository. This is transmitted as a HTTP POST request where the input stream is a MIME type multipart/mixed. This input stream has two parts ordered as follows:

  • an RFC1807 metadata file with MIME type text/x-rfc1807.
  • the content in one of the formats that this repository is capable of accepting as an input format. Refer to the Submit-Formats verb for the method of retrieving the input formats acceptable to a repository.

The meaning of the arguments is as follows:

  • id is a suggested handle that should be given to this document. The repository may reject the submission because the handle is not unique, doesn't conform to the naming conventions for the repository, or if the repository service does not allow client-specified names. If the id argument is omitted then the repository service will assign its own name.
  • partitionpec is a partition specification identifying the partition in the repository into which the document should be deposited. The List-Partitions verb provides information on the available partitions in the repository. This argument is required if the respective repository has multiple partitions.
  • authority is required and indicates the naming authority to associate with this document. The repository must be configured to support the authority specified for this document..

If the submit request is successful the structured return contains:

  • handle of the submitted document.
  • partitionspec indicates the partition specification for the partition which the document was submitted.

Note on Permissions: It is the responsibility of the repository service implementation to provide some level of access control over the submission process. One common mechanism is for a repository service implementation to only accept Submit requests from clients with specific DNS client identifiers.

 Protocol=Dienst;Service=Repository;verb=Submit;ver=2.0;id=handlecorp/970101;partitionspec=compsci;ai In addition an input stream should be supplied with the POST that includes this request. <?xml version="1.0" encoding="UTF-8"?> <Submit version="1.0"> <handle>handlecorp/970101</handle> <partition name="compsci"> <display> Computer Science </display> <partition name="ai"> <display> Artificial Intelligence </display> </partition> <partition> </Submit> Get Submit Formats Submit-Formats 1.0 opt none text/xml 200, 400, 501

Return a structured list of the MIME types of content streams that are accepted by this server in the Submit verb.

 Protocol=Dienst;Service=Repository;verb=Submit-Formats;ver=1.0 <?xml version="1.0" encoding="UTF-8"?> <Submit-Formats version="1.0"> <format>application/postscript</format> <format>application/pdf</format> </Submit-Formats> Get Terms and Conditions Terms 4.0 req handle none text/xml 200, 400, 404, 501

Returns a natural language statement of the terms and conditions for use of the object. The intention is not to create a contract, but only to advise a human of the reasonable expectations of the server or author.

 Protocol=Dienst;Service=Repository;verb=Terms;ver=4.0;handle=handlecorp/970101 <?xml version="1.0" encoding="UTF-8"?> <Terms version="4.0"> <text>Copyright 1999 by the Regents of Oceanview University, Kansas </text> </Terms> Withdraw a Document Withdraw 1.0 opt handle reason, delete, nosave text/xml 200, 400, 401, 404, 501

Removes a document from a repository. The following arguments are available:

  • reason is a text string specifying the reason for withdrawal. A common use of this string is to state a new access point for the document.
  • delete specifies that the information in the bibliographic record (metadata) for the document should be deleted. If not specified, then the metadata will remain, but the content will be deleted.
  • nosave is a suggestion to the repository that the deleted content should not be archived (e.g., maintained by the repository but not accessible through protocol.

If the withdraw request is successful the structured return contains:

  • handle of the withdrawn document.

Note on Permissions: It is the responsibility of the repository service implementation to provide some level of access control over the withdraw process. One common mechanism is for a repository service implementation to only accept Withdraw requests from clients with specific DNS client identifiers. In this case the client is left with the responsibility that the party requesting a withdrawal is authorized to do so.

Note on Policy: The purpose of the Withdraw protocol request is not to dictate policy but provide a mechanism for the implementation of a range of policies. It is expected that each repository will have individual policies for document withdrawal. For example, some repositories may not allow withdrawal at all (will always respond with a 401 error). In other cases, a repository may allow withdrawal of content but insist on maintaining access to the bibliographic record.

Protocol=Dienst;Service=Repository;verb=Withdraw;ver=1.0;handle=handlecorp/970101;reason=I+was+wrong.+The+world+is+not+flat <?xml version="1.0" encoding="UTF-8"?> <Withdraw version="1.0"> <handle>handlecorp/970101</handle> </Withdraw>