White Rose Research Online (OAI-PMH)

openapi: 3.0.3
info:
  title: White Rose Research Online (OAI-PMH 2.0)
  description: >-
    OAI-PMH 2.0 metadata harvesting interface for White Rose Research Online,
    the shared EPrints institutional repository of the Universities of York,
    Leeds and Sheffield. This OpenAPI description models the real OAI-PMH 2.0
    protocol surface as exposed at the live endpoint: a single base URL that
    accepts the six OAI-PMH verbs as query parameters and returns XML responses
    conforming to the OAI-PMH 2.0 schema. Metadata records are returned in any
    of the supported metadata formats (oai_dc, didl, mets, oai_openaire, rdf,
    rioxx, oai_dc_orcid, oai_dc_primo, oai_bibl). All paths, parameters,
    metadata prefixes and error codes below are confirmed against live
    responses; no fields have been invented.
  version: '2.0'
  contact:
    name: White Rose Research Online
    email: [email protected]
  license:
    name: OAI-PMH 2.0
    url: http://www.openarchives.org/OAI/openarchivesprotocol.html
servers:
  - url: https://eprints.whiterose.ac.uk/cgi
    description: White Rose Research Online OAI-PMH base
paths:
  /oai2:
    get:
      summary: OAI-PMH request dispatch
      description: >-
        Single OAI-PMH endpoint. The request is dispatched by the required
        `verb` parameter. Each verb accepts its own set of additional
        parameters as defined by the OAI-PMH 2.0 protocol. All responses are
        XML conforming to the OAI-PMH 2.0 schema.
      operationId: oaiRequest
      parameters:
        - name: verb
          in: query
          required: true
          description: The OAI-PMH protocol request type.
          schema:
            type: string
            enum:
              - Identify
              - ListMetadataFormats
              - ListSets
              - ListIdentifiers
              - ListRecords
              - GetRecord
        - name: identifier
          in: query
          required: false
          description: >-
            The unique OAI identifier of an item. Required for GetRecord;
            optional for ListMetadataFormats. Example
            oai:eprints.whiterose.ac.uk:5
          schema:
            type: string
            example: oai:eprints.whiterose.ac.uk:5
        - name: metadataPrefix
          in: query
          required: false
          description: >-
            The metadata format in which records should be returned. Required
            for GetRecord, ListRecords and ListIdentifiers (unless resuming with
            a resumptionToken). Confirmed supported formats are listed in the
            enum.
          schema:
            type: string
            enum:
              - oai_dc
              - oai_bibl
              - oai_dc_orcid
              - oai_dc_primo
              - oai_openaire
              - didl
              - mets
              - rdf
              - rioxx
            example: oai_dc
        - name: from
          in: query
          required: false
          description: >-
            Lower bound for selective harvesting by datestamp. Granularity is
            YYYY-MM-DDThh:mm:ssZ.
          schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
        - name: until
          in: query
          required: false
          description: >-
            Upper bound for selective harvesting by datestamp. Granularity is
            YYYY-MM-DDThh:mm:ssZ.
          schema:
            type: string
            format: date-time
            example: '2024-12-31T23:59:59Z'
        - name: set
          in: query
          required: false
          description: >-
            Restricts a list request to records belonging to the given set. Set
            specs are hex-encoded as returned by ListSets.
          schema:
            type: string
        - name: resumptionToken
          in: query
          required: false
          description: >-
            Flow control token returned by a previous incomplete list response.
            When supplied it is the only other argument allowed besides verb.
          schema:
            type: string
      responses:
        '200':
          description: >-
            A valid OAI-PMH 2.0 XML response. May contain the requested data or
            an OAI-PMH error element (e.g. badArgument, idDoesNotExist,
            cannotDisseminateFormat, noRecordsMatch, badResumptionToken,
            badVerb, noMetadataFormats, noSetHierarchy).
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/OAIPMHResponse'
components:
  schemas:
    OAIPMHResponse:
      type: object
      description: Root OAI-PMH 2.0 response envelope.
      properties:
        responseDate:
          type: string
          format: date-time
          example: '2026-06-04T03:13:43Z'
        request:
          type: string
          description: Echo of the request base URL and arguments.
          example: https://eprints.whiterose.ac.uk/cgi/oai2
        Identify:
          $ref: '#/components/schemas/Identify'
        GetRecord:
          type: object
          properties:
            record:
              $ref: '#/components/schemas/Record'
        ListRecords:
          type: object
          properties:
            record:
              type: array
              items:
                $ref: '#/components/schemas/Record'
            resumptionToken:
              type: string
        error:
          $ref: '#/components/schemas/OAIError'
    Identify:
      type: object
      description: Repository description returned by the Identify verb.
      properties:
        repositoryName:
          type: string
          example: White Rose Research Online
        baseURL:
          type: string
          format: uri
          example: https://eprints.whiterose.ac.uk/cgi/oai2
        protocolVersion:
          type: string
          example: '2.0'
        adminEmail:
          type: string
          format: email
          example: [email protected]
        earliestDatestamp:
          type: string
          format: date-time
          example: '2007-08-05T17:37:28Z'
        deletedRecord:
          type: string
          enum: [no, persistent, transient]
          example: persistent
        granularity:
          type: string
          example: YYYY-MM-DDThh:mm:ssZ
    Record:
      type: object
      description: An OAI-PMH record consisting of a header and (unless deleted) metadata.
      properties:
        header:
          $ref: '#/components/schemas/RecordHeader'
        metadata:
          type: object
          description: >-
            Metadata payload in the requested metadataPrefix format. For oai_dc
            this is a Dublin Core element set.
          properties:
            dc:
              $ref: '#/components/schemas/DublinCore'
    RecordHeader:
      type: object
      properties:
        identifier:
          type: string
          example: oai:eprints.whiterose.ac.uk:5
        datestamp:
          type: string
          format: date-time
          example: '2016-10-28T17:09:02Z'
        status:
          type: string
          description: Present and equal to "deleted" for tombstone records.
          enum: [deleted]
        setSpec:
          type: array
          items:
            type: string
    DublinCore:
      type: object
      description: >-
        Simple Dublin Core (oai_dc) element set. Each element is repeatable per
        the DC 1.1 namespace.
      properties:
        title:
          type: array
          items:
            type: string
          example: ['Current practices in managing acutely disturbed patients at three hospitals in Rio de Janeiro-Brazil: a prevalence study']
        creator:
          type: array
          items:
            type: string
          example: ['Adams, C.E.', 'Huf, G']
        subject:
          type: array
          items:
            type: string
        description:
          type: array
          items:
            type: string
        relation:
          type: array
          items:
            type: string
          example: ['https://eprints.whiterose.ac.uk/id/eprint/5/']
        date:
          type: array
          items:
            type: string
        type:
          type: array
          items:
            type: string
        identifier:
          type: array
          items:
            type: string
    OAIError:
      type: object
      description: OAI-PMH protocol error.
      properties:
        code:
          type: string
          enum:
            - badArgument
            - badResumptionToken
            - badVerb
            - cannotDisseminateFormat
            - idDoesNotExist
            - noRecordsMatch
            - noMetadataFormats
            - noSetHierarchy
        message:
          type: string