openapi: 3.1.0
info:
title: Deep Blue Documents OAI-PMH
version: '2.0'
summary: >-
Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH 2.0) interface to
Deep Blue, the University of Michigan Library's DSpace institutional repository.
description: |
Deep Blue is the University of Michigan Library's institutional repository of articles,
dissertations, theses, archival finding aids and other scholarly works. Its DSpace backend
exposes a standard OAI-PMH 2.0 harvesting interface on a University of Michigan host.
## Operator
`x-operator: institution`. The host
`backend.production.deepblue-documents.lib.umich.edu` is under `umich.edu`, the University
of Michigan's own registrable domain, and the `Identify` response names
`repositoryName: Deep Blue`, `repositoryIdentifier: deepblue.lib.umich.edu` and
`adminEmail: deepblue@umich.edu`. The repository *software* is DSpace (open source,
LYRASIS) — the deployment, the host, the content and the administrative contact are the
University of Michigan Library's.
## Provenance of this document
**The University of Michigan does not publish an OpenAPI description of this endpoint.**
This document was written by API Evangelist by probing the live endpoint on 2026-08-19.
Every operation, parameter, error code and example in it corresponds to a request that was
actually issued and a response that was actually returned — see `examples/` in this repo for
the verbatim captures. Nothing here is inferred from the OAI-PMH specification alone.
## Response format
All responses are `text/xml` OAI-PMH envelopes and all responses — including protocol
errors — are returned with HTTP `200`. Errors are carried in an `<error code="...">`
element inside the envelope, not in the status line. Harvesters must parse the body.
## Access
Unauthenticated and open. No API key, no OAuth, no registration, no scope model. No
published rate limit or terms-of-use document was found for this endpoint.
contact:
name: Deep Blue
email: deepblue@umich.edu
url: https://www.lib.umich.edu/collections/deep-blue-repositories
license:
name: Open Archives Initiative Protocol for Metadata Harvesting 2.0
url: http://www.openarchives.org/OAI/openarchivesprotocol.html
x-operator: institution
x-operator-evidence: >-
Host backend.production.deepblue-documents.lib.umich.edu is under umich.edu. Identify returns
repositoryName "Deep Blue", repositoryIdentifier "deepblue.lib.umich.edu",
adminEmail "deepblue@umich.edu".
x-provenance:
generated: '2026-08-19'
method: probed
source: https://backend.production.deepblue-documents.lib.umich.edu/server/oai/request
probed_at: '2026-08-19T21:28:21Z'
probes:
- '?verb=Identify -> 200 text/xml 1361 bytes'
- '?verb=ListMetadataFormats -> 200 text/xml 3119 bytes'
- '?verb=ListSets -> 200 text/xml 11487 bytes (completeListSize 726)'
- '?verb=ListIdentifiers&metadataPrefix=oai_dc -> 200 text/xml 21481 bytes'
- '?verb=ListRecords&metadataPrefix=oai_dc -> 200 text/xml 499532 bytes'
- '?verb=GetRecord&identifier=oai:deepblue.lib.umich.edu:2027.42/61022&metadataPrefix=oai_dc -> 200 text/xml 5703 bytes'
- '?verb=Nope -> 200 error code="badVerb"'
- '?verb=GetRecord -> 200 error code="badArgument"'
- '?verb=GetRecord&metadataPrefix=bogus -> 200 error code="cannotDisseminateFormat"'
- '?verb=GetRecord&identifier=...2027.42/000000 -> 200 error code="idDoesNotExist"'
servers:
- url: https://backend.production.deepblue-documents.lib.umich.edu/server/oai
description: Deep Blue Documents production OAI-PMH endpoint (University of Michigan Library)
tags:
- name: Repository
description: Repository-level description and capability discovery.
- name: Harvesting
description: Record and identifier harvesting with resumption tokens.
security: []
paths:
/request:
get:
tags: [Repository, Harvesting]
operationId: oaiRequest
summary: Issue an OAI-PMH request
description: |
Single OAI-PMH 2.0 request endpoint. The `verb` parameter selects the operation. All
six protocol verbs were probed live against this host on 2026-08-19 and all returned
HTTP 200 with a well-formed OAI-PMH envelope.
Argument rules observed on this deployment:
- `Identify`, `ListMetadataFormats`, `ListSets` take no further required arguments.
- `ListRecords` and `ListIdentifiers` require either `metadataPrefix` or `resumptionToken`,
and accept `set`, `from` and `until`.
- `GetRecord` requires both `identifier` and `metadataPrefix`; omitting them returns
`badArgument`.
- `granularity` is `YYYY-MM-DDThh:mm:ssZ` and `deletedRecord` is `transient`
(from the live Identify response).
parameters:
- name: verb
in: query
required: true
description: The OAI-PMH verb to execute.
schema:
type: string
enum:
- Identify
- ListMetadataFormats
- ListSets
- ListIdentifiers
- ListRecords
- GetRecord
examples:
identify: { value: Identify }
getRecord: { value: GetRecord }
- name: metadataPrefix
in: query
required: false
description: >-
Metadata format to disseminate. Required for GetRecord, and for ListRecords /
ListIdentifiers when no resumptionToken is supplied. The twelve prefixes this
deployment actually advertises are enumerated in the enum below, read from a live
ListMetadataFormats response.
schema:
type: string
enum:
- oai_dc
- qdc
- mods
- mets
- marc
- rdf
- ore
- didl
- dim
- xoai
- etdms
- uketd_dc
- name: identifier
in: query
required: false
description: >-
OAI identifier of a single record. Scheme `oai`, repository identifier
`deepblue.lib.umich.edu`, delimiter `:`. Sample identifier advertised by Identify:
`oai:deepblue.lib.umich.edu:2027.42/1234`. The local part is a Handle under the
`2027.42` prefix.
schema:
type: string
pattern: '^oai:deepblue\.lib\.umich\.edu:2027\.42/[0-9]+$'
example: 'oai:deepblue.lib.umich.edu:2027.42/61022'
- name: set
in: query
required: false
description: >-
Restrict harvesting to one set. This deployment advertises 726 sets
(completeListSize on ListSets), named `com_2027.42_<id>` for DSpace communities and
`col_2027.42_<id>` for collections.
schema:
type: string
pattern: '^(com|col)_2027\.42_[0-9]+$'
example: com_2027.42_65133
- name: from
in: query
required: false
description: >-
Lower bound on record datestamp, inclusive. Granularity
`YYYY-MM-DDThh:mm:ssZ` per the live Identify response. Earliest datestamp in this
repository is `2005-08-29T23:07:21Z`.
schema:
type: string
format: date-time
example: '2026-01-01T00:00:00Z'
- name: until
in: query
required: false
description: Upper bound on record datestamp, inclusive.
schema:
type: string
format: date-time
- name: resumptionToken
in: query
required: false
description: >-
Continuation token from a previous incomplete list. Observed form on this
deployment is `<from>/<until>/<set>/<metadataPrefix>/<cursor>` — e.g. the ListSets
response returned `////100` with `completeListSize="726" cursor="0"`. When
resumptionToken is supplied no other argument may be.
schema:
type: string
example: '////100'
responses:
'200':
description: >-
A well-formed OAI-PMH 2.0 envelope. Protocol errors are ALSO returned with status
200, carried in an `<error code="...">` element — status code alone is not a
success signal on this API.
content:
text/xml:
schema:
$ref: '#/components/schemas/OAIPMHEnvelope'
examples:
identify:
summary: Identify (verbatim live capture, 2026-08-19)
externalValue: ../examples/deep-blue-documents-oai-identify.xml
listMetadataFormats:
summary: ListMetadataFormats — 12 formats (verbatim live capture)
externalValue: ../examples/deep-blue-documents-oai-listmetadataformats.xml
getRecord:
summary: GetRecord oai_dc (verbatim live capture)
externalValue: ../examples/deep-blue-documents-oai-getrecord.xml
errors:
summary: The four error codes actually reproduced against this host
externalValue: ../examples/deep-blue-documents-oai-errors.xml
components:
schemas:
OAIPMHEnvelope:
type: object
description: >-
OAI-PMH 2.0 response envelope, namespace `http://www.openarchives.org/OAI/2.0/`.
Exactly one of the verb payloads or `error` is present alongside `responseDate` and
`request`.
required: [responseDate, request]
properties:
responseDate:
type: string
format: date-time
description: UTC timestamp the response was generated.
request:
type: string
format: uri
description: Echo of the base URL, with the request arguments as XML attributes.
error:
$ref: '#/components/schemas/OAIError'
Identify:
$ref: '#/components/schemas/Identify'
ListMetadataFormats:
type: array
items: { $ref: '#/components/schemas/MetadataFormat' }
ListSets:
type: array
items: { $ref: '#/components/schemas/Set' }
ListIdentifiers:
type: array
items: { $ref: '#/components/schemas/RecordHeader' }
ListRecords:
type: array
items: { $ref: '#/components/schemas/Record' }
GetRecord:
$ref: '#/components/schemas/Record'
Identify:
type: object
description: Repository description. Values below are those returned live on 2026-08-19.
required: [repositoryName, baseURL, protocolVersion, adminEmail, earliestDatestamp, deletedRecord, granularity]
properties:
repositoryName: { type: string, example: Deep Blue }
baseURL:
type: string
format: uri
example: https://backend.production.deepblue-documents.lib.umich.edu/server/oai/request
protocolVersion: { type: string, const: '2.0' }
adminEmail: { type: string, format: email, example: deepblue@umich.edu }
earliestDatestamp: { type: string, format: date-time, example: '2005-08-29T23:07:21Z' }
deletedRecord: { type: string, enum: [no, persistent, transient], example: transient }
granularity: { type: string, example: 'YYYY-MM-DDThh:mm:ssZ' }
oaiIdentifier:
type: object
properties:
scheme: { type: string, example: oai }
repositoryIdentifier: { type: string, example: deepblue.lib.umich.edu }
delimiter: { type: string, example: ':' }
sampleIdentifier: { type: string, example: 'oai:deepblue.lib.umich.edu:2027.42/1234' }
MetadataFormat:
type: object
required: [metadataPrefix, schema, metadataNamespace]
properties:
metadataPrefix: { type: string, example: oai_dc }
schema: { type: string, format: uri, example: 'http://www.openarchives.org/OAI/2.0/oai_dc.xsd' }
metadataNamespace: { type: string, format: uri, example: 'http://www.openarchives.org/OAI/2.0/oai_dc/' }
Set:
type: object
required: [setSpec, setName]
properties:
setSpec: { type: string, example: com_2027.42_65133 }
setName: { type: string, example: 'Archival Collections -- Bentley Library' }
RecordHeader:
type: object
required: [identifier, datestamp]
properties:
identifier: { type: string, example: 'oai:deepblue.lib.umich.edu:2027.42/61022' }
datestamp: { type: string, format: date-time, example: '2021-09-29T22:07:51Z' }
setSpec:
type: array
items: { type: string }
status:
type: string
enum: [deleted]
description: Present only on deleted records. This repository reports deletions as transient.
Record:
type: object
required: [header]
properties:
header: { $ref: '#/components/schemas/RecordHeader' }
metadata:
type: object
description: >-
Metadata payload in the requested prefix. For `oai_dc` this is an
`oai_dc:dc` element carrying repeatable Dublin Core elements
(`dc:title`, `dc:creator`, `dc:subject`, `dc:date`, `dc:identifier`, `dc:type`,
`dc:rights`, `dc:language`, `dc:description`).
OAIError:
type: object
description: >-
Protocol error. Carried inside a 200 response. Only the four codes below were
reproduced against this host; the OAI-PMH specification defines others.
required: [code]
properties:
code:
type: string
enum: [badVerb, badArgument, cannotDisseminateFormat, idDoesNotExist, badResumptionToken, noRecordsMatch, noMetadataFormats, noSetHierarchy]
message:
type: string
description: Human-readable text content of the error element.