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.