Research Repository UCD — OAI-PMH 2.0

openapi: 3.1.0
# ---------------------------------------------------------------------------
# PROVENANCE
#   generated: '2026-08-30'
#   method: derived
#   source: >-
#     Live probes of https://researchrepository.ucd.ie/server/oai/request on
#     2026-08-30. Every path, parameter, status code and protocol error code
#     below was observed in a real response; nothing is taken from prose.
#   x-operator: institution
#   NOTE: University College Dublin does NOT publish an OpenAPI description of
#   this endpoint. This document is API Evangelist's derived description of a
#   public, standards-defined (OAI-PMH 2.0) interface that UCD operates under
#   its own registrable domain. It is not a UCD artifact and must never be
#   credited to UCD as something they published.
# ---------------------------------------------------------------------------
info:
  title: Research Repository UCD — OAI-PMH 2.0
  version: '2.0'
  summary: OAI-PMH 2.0 metadata harvesting interface for Research Repository UCD.
  description: >-
    Research Repository UCD is University College Dublin's open-access
    institutional repository. It exposes an Open Archives Initiative Protocol
    for Metadata Harvesting (OAI-PMH) version 2.0 interface at
    https://researchrepository.ucd.ie/server/oai/request, on UCD's own
    registrable domain, identified by the repository identifier
    `researchrepository.ucd.ie` and administered from research.repository@ucd.ie.


    The interface is anonymous and read-only. All six OAI-PMH verbs were
    observed returning HTTP 200 with a well-formed OAI-PMH envelope on
    2026-08-30, and the three protocol error conditions exercised (badVerb,
    cannotDisseminateFormat, idDoesNotExist) returned the correct OAI-PMH error
    codes inside a 200 response, as the protocol requires. A ListIdentifiers
    call reported completeListSize 17167.


    OPERATOR NOTE: the repository software is DSpace-CRIS (DSpace 7.6.1,
    cris-2023.02.05) and researchrepository.ucd.ie resolves through a CNAME to
    ucd7.4science.cloud / ucd-researchrepository.prod.4science.cloud, so the
    platform is hosted by 4Science. The OAI-PMH endpoint, the repository
    identifier, the content and the administrative contact are UCD's; the
    hosting and the software are not. The DSpace REST API served from the same
    deployment is the vendor's generic contract and is recorded separately in
    apis.yml as x-operator: tenant.
  contact:
    name: Research Repository UCD
    email: research.repository@ucd.ie
    url: https://researchrepository.ucd.ie/
  license:
    name: OAI-PMH 2.0 protocol specification
    url: https://www.openarchives.org/OAI/openarchivesprotocol.html
servers:
  - url: https://researchrepository.ucd.ie/server
    description: Research Repository UCD (DSpace-CRIS 7.6.1) — production
tags:
  - name: OAI-PMH
    description: OAI-PMH 2.0 harvesting verbs.
paths:
  /oai/request:
    get:
      operationId: oaiRequest
      summary: Issue an OAI-PMH 2.0 request
      description: >-
        Single OAI-PMH 2.0 endpoint. The `verb` query parameter selects the
        operation; the remaining parameters are those the selected verb allows.
        All responses are `text/xml` OAI-PMH envelopes returned with HTTP 200,
        including protocol errors, which are carried in an `<error code="...">`
        element rather than an HTTP status.
      tags: [OAI-PMH]
      parameters:
        - name: verb
          in: query
          required: true
          description: The OAI-PMH verb to invoke.
          schema:
            type: string
            enum:
              - Identify
              - ListMetadataFormats
              - ListSets
              - ListIdentifiers
              - ListRecords
              - GetRecord
          examples:
            identify:
              value: Identify
        - name: metadataPrefix
          in: query
          required: false
          description: >-
            Metadata format to disseminate. Required for ListIdentifiers,
            ListRecords and GetRecord. Fourteen prefixes were observed live.
          schema:
            type: string
            enum:
              - oai_dc
              - qdc
              - dim
              - didl
              - mets
              - mods
              - ore
              - rdf
              - marc
              - marc21
              - etdms
              - uketd_dc
              - rian_dc
              - rms_oai
          examples:
            dublinCore:
              value: oai_dc
        - name: identifier
          in: query
          required: false
          description: >-
            OAI identifier of a single record. Required for GetRecord. Form:
            `oai:researchrepository.ucd.ie:10197/<handle-suffix>`.
          schema:
            type: string
            pattern: '^oai:researchrepository\.ucd\.ie:10197/\d+$'
          examples:
            thesis:
              value: 'oai:researchrepository.ucd.ie:10197/30754'
        - name: set
          in: query
          required: false
          description: >-
            Restrict a list request to one set. Set specs observed live take the
            form `com_10197_<id>` for communities and `col_10197_<id>` for
            collections.
          schema:
            type: string
          examples:
            college:
              value: com_10197_6669
        - name: from
          in: query
          required: false
          description: Lower bound on record datestamp (granularity YYYY-MM-DDThh:mm:ssZ).
          schema:
            type: string
            format: date-time
        - name: until
          in: query
          required: false
          description: Upper bound on record datestamp (granularity YYYY-MM-DDThh:mm:ssZ).
          schema:
            type: string
            format: date-time
        - name: resumptionToken
          in: query
          required: false
          description: >-
            Flow-control token returned by an incomplete list response. Observed
            form `oai_dc////100`, alongside `completeListSize` and `cursor`
            attributes.
          schema:
            type: string
      responses:
        '200':
          description: >-
            An OAI-PMH envelope. Successful requests carry the verb element;
            protocol errors carry an `<error>` element with an OAI-PMH error
            code — both are returned with HTTP 200 as the protocol requires.
          content:
            text/xml:
              schema:
                type: string
                contentMediaType: text/xml
                description: OAI-PMH 2.0 XML envelope.
              examples:
                identify:
                  summary: verb=Identify (observed 2026-08-30)
                  externalValue: ../examples/ucd-oai-pmh-identify-example.xml
                badVerb:
                  summary: verb=Bogus — protocol error inside a 200 (observed 2026-08-30)
                  externalValue: ../examples/ucd-oai-pmh-badverb-example.xml
  /oai/openairecris:
    get:
      operationId: oaiOpenAireCris
      summary: Issue an OAI-PMH request against the OpenAIRE CRIS context
      description: >-
        Second OAI-PMH base URL, advertised by the Identify response's OpenAIRE
        CERIF `<Service>` description with Compatibility
        `OpenAIRE_Service_Compatibility#1.1`. Serves the OpenAIRE Guidelines for
        CRIS Managers 1.1 CERIF profile. Verified live on 2026-08-30:
        `?verb=Identify` returns repositoryName "Research Repository UCD".
      tags: [OAI-PMH]
      parameters:
        - name: verb
          in: query
          required: true
          schema:
            type: string
            enum:
              - Identify
              - ListMetadataFormats
              - ListSets
              - ListIdentifiers
              - ListRecords
              - GetRecord
        - name: metadataPrefix
          in: query
          required: false
          description: OpenAIRE CERIF profile prefix.
          schema:
            type: string
          examples:
            cerif:
              value: oai_cerif_openaire
        - name: set
          in: query
          required: false
          schema:
            type: string
          examples:
            persons:
              value: openaire_cris_persons
      responses:
        '200':
          description: OAI-PMH 2.0 envelope carrying OpenAIRE CERIF 1.1 records.
          content:
            text/xml:
              schema:
                type: string
                contentMediaType: text/xml