openapi: 3.0.3
info:
  title: Lancaster EPrints OAI-PMH 2.0 Interface
  description: >-
    OpenAPI 3.0 description of the live OAI-PMH 2.0 metadata harvesting interface
    exposed by the Lancaster EPrints institutional repository (EPrints 3.4.5).
    The interface is a single HTTP endpoint that dispatches on the required
    "verb" query parameter and returns OAI-PMH XML envelopes. This description
    was derived by probing the live endpoint; only verbs, parameters, metadata
    formats, and response objects observed in production are represented.
  version: '2.0'
  contact:
    name: Lancaster University Library (DIT)
    email: library.dit@lancaster.ac.uk
  license:
    name: OAI-PMH 2.0
    url: http://www.openarchives.org/OAI/openarchivesprotocol.html
externalDocs:
  description: OAI-PMH Identify response (live)
  url: https://eprints.lancs.ac.uk/cgi/oai2?verb=Identify
servers:
  - url: https://eprints.lancs.ac.uk/cgi
    description: Lancaster EPrints OAI-PMH base
paths:
  /oai2:
    get:
      operationId: oaiRequest
      summary: OAI-PMH request dispatch
      description: >-
        Single OAI-PMH endpoint. The "verb" parameter selects the operation.
        Responses are OAI-PMH XML envelopes (Content-Type text/xml). Parameter
        applicability depends on the verb per the OAI-PMH 2.0 specification.
      parameters:
        - name: verb
          in: query
          required: true
          description: The OAI-PMH verb to execute.
          schema:
            type: string
            enum:
              - Identify
              - ListMetadataFormats
              - ListSets
              - ListIdentifiers
              - ListRecords
              - GetRecord
        - name: metadataPrefix
          in: query
          required: false
          description: >-
            Metadata format to disseminate. Required for ListRecords,
            ListIdentifiers, and GetRecord (unless a resumptionToken is used).
            Observed supported formats on this repository.
          schema:
            type: string
            enum: [didl, mets, oai_bibl, oai_dc, rdf, rioxx, uketd_dc]
        - name: identifier
          in: query
          required: false
          description: >-
            OAI item identifier, e.g. oai:eprints.lancs.ac.uk:10175. Required
            for GetRecord.
          schema:
            type: string
            example: oai:eprints.lancs.ac.uk:9
        - name: set
          in: query
          required: false
          description: Set spec to selectively harvest a subset of records.
          schema:
            type: string
        - name: from
          in: query
          required: false
          description: >-
            Lower bound (inclusive) for selective harvesting by datestamp.
            Granularity YYYY-MM-DDThh:mm:ssZ.
          schema:
            type: string
            format: date-time
        - name: until
          in: query
          required: false
          description: >-
            Upper bound (inclusive) for selective harvesting by datestamp.
            Granularity YYYY-MM-DDThh:mm:ssZ.
          schema:
            type: string
            format: date-time
        - name: resumptionToken
          in: query
          required: false
          description: >-
            Flow-control token returned in an incomplete list response; used to
            request the next page. Exclusive of other selective arguments.
          schema:
            type: string
      responses:
        '200':
          description: OAI-PMH XML envelope (success or OAI error element).
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/OAIPMHResponse'
components:
  schemas:
    OAIPMHResponse:
      type: object
      description: >-
        Root OAI-PMH XML envelope. Carries responseDate, the echoed request,
        and exactly one verb-specific payload or an error element. Modeled
        structurally here since the wire format is XML.
      properties:
        responseDate:
          type: string
          format: date-time
        request:
          type: string
          description: Echoed base URL with the request attributes (verb, etc.).
      required: [responseDate, request]
    Identify:
      type: object
      description: Repository description returned by the Identify verb.
      properties:
        repositoryName:
          type: string
          example: Lancaster EPrints
        baseURL:
          type: string
          format: uri
          example: https://eprints.lancs.ac.uk/cgi/oai2
        protocolVersion:
          type: string
          example: '2.0'
        adminEmail:
          type: string
          format: email
          example: library.dit@lancaster.ac.uk
        earliestDatestamp:
          type: string
          format: date-time
          example: '2019-06-10T15:56:35Z'
        deletedRecord:
          type: string
          example: persistent
        granularity:
          type: string
          example: YYYY-MM-DDThh:mm:ssZ
    MetadataFormat:
      type: object
      properties:
        metadataPrefix:
          type: string
          example: oai_dc
        schema:
          type: string
          format: uri
        metadataNamespace:
          type: string
          format: uri
      required: [metadataPrefix, schema, metadataNamespace]
    Header:
      type: object
      description: OAI record header.
      properties:
        identifier:
          type: string
          example: oai:eprints.lancs.ac.uk:9
        datestamp:
          type: string
          format: date-time
        status:
          type: string
          enum: [deleted]
        setSpec:
          type: array
          items:
            type: string
      required: [identifier, datestamp]
    DublinCoreRecord:
      type: object
      description: >-
        oai_dc (simple Dublin Core) metadata for a single EPrints item, as
        observed in ListRecords/GetRecord responses.
      properties:
        title:
          type: string
        creator:
          type: array
          items:
            type: string
        date:
          type: string
        type:
          type: array
          items:
            type: string
        identifier:
          type: array
          items:
            type: string
        subject:
          type: array
          items:
            type: string
        description:
          type: string
        publisher:
          type: string
        relation:
          type: array
          items:
            type: string
    Record:
      type: object
      properties:
        header:
          $ref: '#/components/schemas/Header'
        metadata:
          $ref: '#/components/schemas/DublinCoreRecord'
      required: [header]
    OAIError:
      type: object
      description: OAI-PMH error element.
      properties:
        code:
          type: string
          enum:
            - badArgument
            - badResumptionToken
            - badVerb
            - cannotDisseminateFormat
            - idDoesNotExist
            - noRecordsMatch
            - noMetadataFormats
            - noSetHierarchy
        message:
          type: string