University of York Research Portal OAI-PMH

# authorship: generated by API Evangelist from live probes of the operator's own endpoints.
# The document is ours; the facts in it were measured, not claimed. `method: probed` below
# records HOW it was obtained; this header records WHO wrote it. An unmarked artifact would
# be credited to the institution as though they published it, and they did not.
openapi: 3.1.0
info:
  title: University of York Research Portal OAI-PMH
  version: '2.0'
  summary: OAI-PMH 2.0 metadata harvesting over the University of York's research portal, on the University's own host.
  description: >-
    OAI-PMH 2.0 harvesting endpoint at https://pure.york.ac.uk/ws/oai. The Identify response
    names the repository "The University of York", gives an adminEmail of pure-support@york.ac.uk,
    and a baseURL under the University's own registrable domain — which is why this surface is
    recorded as institution-operated rather than as a vendor's.

    BE CLEAR ABOUT WHAT IS AND IS NOT THE UNIVERSITY'S HERE. The repository software is Elsevier
    Pure, and Pure's own REST Web Service (https://pure.york.ac.uk/ws/api, which serves a 1.1 MB
    vendor OpenAPI document and requires an API key) is ELSEVIER'S CONTRACT, not York's. It is
    deliberately NOT described in this repository; it is recorded in apis.yml as a tenant
    relationship instead. What IS described below is the OAI-PMH 2.0 protocol surface — an open
    Open Archives Initiative standard — as the University of York deploys it on its own host, with
    the sets, metadata prefixes and identifier syntax this specific deployment actually returns.

    Every verb, set, metadata prefix, identifier form and error below was confirmed against live
    responses on 2026-08-30. Nothing has been fabricated. Responses are XML; OAI-PMH protocol
    errors are returned inside a 200 response as an <error> element, which is standard and is
    recorded as such.
  contact:
    name: University of York Pure Support
    email: pure-support@york.ac.uk
    url: https://pure.york.ac.uk/portal/
  license:
    name: OAI-PMH 2.0
    url: http://www.openarchives.org/OAI/openarchivesprotocol.html
x-operator: institution
x-operator-note: >-
  Host pure.york.ac.uk is under york.ac.uk and the Identify response self-identifies as
  "The University of York". The underlying product is Elsevier Pure; its proprietary REST API is
  recorded separately as a tenant relationship and its contract is NOT saved here.
x-provenance:
  method: probed
  generated: '2026-08-30'
  source:
    - https://pure.york.ac.uk/ws/oai?verb=Identify
    - https://pure.york.ac.uk/ws/oai?verb=ListMetadataFormats
    - https://pure.york.ac.uk/ws/oai?verb=ListSets
    - https://pure.york.ac.uk/ws/oai?verb=ListIdentifiers&metadataPrefix=oai_dc
    - https://pure.york.ac.uk/ws/oai?verb=ListRecords&metadataPrefix=oai_dc&set=publications:year1960
    - https://pure.york.ac.uk/ws/oai?verb=GetRecord&metadataPrefix=oai_dc&identifier=...
servers:
  - url: https://pure.york.ac.uk/ws
    description: University of York research portal OAI-PMH base
tags:
  - name: OAI-PMH
    description: Open Archives Initiative Protocol for Metadata Harvesting 2.0.
paths:
  /oai:
    get:
      summary: OAI-PMH 2.0 request dispatch
      description: >-
        A single endpoint dispatched by the required `verb` argument. All six OAI-PMH 2.0 verbs
        were confirmed live on this deployment. Responses are XML conforming to the OAI-PMH 2.0
        schema. Protocol errors are returned with HTTP 200 and an <error code="..."> element.
      operationId: oaiRequest
      tags: [OAI-PMH]
      security: []
      parameters:
        - name: verb
          in: query
          required: true
          description: The OAI-PMH protocol request. All six confirmed live on this endpoint.
          schema:
            type: string
            enum: [Identify, ListMetadataFormats, ListSets, ListIdentifiers, ListRecords, GetRecord]
          example: Identify
        - name: identifier
          in: query
          required: false
          description: >-
            OAI identifier of a single item. Required for GetRecord; optional for
            ListMetadataFormats. This deployment's identifier syntax is
            `oai:https://pure.york.ac.uk/:{entity}/{uuid}` where entity is `publications` or
            `persons`.
          schema: { type: string }
          example: 'oai:https://pure.york.ac.uk/:publications/d5ff166f-d255-4cab-9688-253729e80ee0'
        - name: metadataPrefix
          in: query
          required: false
          description: >-
            Metadata format. This deployment serves exactly five, confirmed via
            ListMetadataFormats: mods, xmetadiss, nl_didl, oai_dc, qdc. Note that
            oai_dc_orcid is NOT offered here — ORCID iDs are carried inside the `mods` format
            as mods:nameIdentifier type="orcid".
          schema:
            type: string
            enum: [mods, xmetadiss, nl_didl, oai_dc, qdc]
          example: oai_dc
        - name: set
          in: query
          required: false
          description: >-
            Restricts a list request to one set. Confirmed sets include `persons:all`,
            `publications:all`, `publications:withFiles` and per-year sets of the form
            `publications:year{YYYY}` (observed from 1960).
          schema: { type: string }
          example: 'publications:all'
        - name: from
          in: query
          required: false
          description: Lower-bound datestamp for selective harvesting. Granularity YYYY-MM-DDThh:mm:ssZ.
          schema: { type: string, format: date-time }
        - name: until
          in: query
          required: false
          description: Upper-bound datestamp for selective harvesting.
          schema: { type: string, format: date-time }
        - name: resumptionToken
          in: query
          required: false
          description: Flow-control token from a previous incomplete list response.
          schema: { type: string }
      responses:
        '200':
          description: >-
            An OAI-PMH 2.0 XML response. May carry a result element (Identify, ListSets,
            ListMetadataFormats, ListIdentifiers, ListRecords, GetRecord) OR an <error> element —
            both are HTTP 200 in this protocol.
          content:
            text/xml:
              schema: { $ref: '#/components/schemas/OAIPMHResponse' }
components:
  securitySchemes: {}
  schemas:
    OAIPMHResponse:
      type: object
      description: Root OAI-PMH 2.0 response envelope.
      properties:
        responseDate: { type: string, format: date-time }
        request: { type: string, format: uri, example: 'https://pure.york.ac.uk/ws/oai' }
        Identify: { $ref: '#/components/schemas/Identify' }
        ListMetadataFormats:
          type: object
          properties:
            metadataFormat:
              type: array
              items: { $ref: '#/components/schemas/MetadataFormat' }
        ListSets:
          type: object
          properties:
            set:
              type: array
              items: { $ref: '#/components/schemas/Set' }
        ListIdentifiers:
          type: object
          properties:
            header:
              type: array
              items: { $ref: '#/components/schemas/RecordHeader' }
            resumptionToken: { type: string }
        ListRecords:
          type: object
          properties:
            record:
              type: array
              items: { $ref: '#/components/schemas/Record' }
            resumptionToken: { type: string }
        GetRecord:
          type: object
          properties:
            record: { $ref: '#/components/schemas/Record' }
        error: { $ref: '#/components/schemas/OAIError' }
    Identify:
      type: object
      description: Repository description, as returned by this deployment on 2026-08-30.
      properties:
        repositoryName: { type: string, const: The University of York }
        baseURL: { type: string, format: uri, const: 'https://pure.york.ac.uk/ws/oai' }
        protocolVersion: { type: string, const: '2.0' }
        adminEmail: { type: string, format: email, const: pure-support@york.ac.uk }
        earliestDatestamp: { type: string, format: date-time, example: '2014-10-14T11:47:31Z' }
        deletedRecord: { type: string, const: 'no' }
        granularity: { type: string, const: 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 }
    Set:
      type: object
      properties:
        setSpec: { type: string, example: 'publications:all' }
        setName: { type: string, example: PURE publications }
    RecordHeader:
      type: object
      properties:
        identifier: { type: string }
        datestamp: { type: string, format: date-time }
        setSpec: { type: array, items: { type: string } }
    Record:
      type: object
      properties:
        header: { $ref: '#/components/schemas/RecordHeader' }
        metadata:
          type: object
          description: >-
            Payload in the requested metadataPrefix. For oai_dc this is a simple Dublin Core
            element set; for mods it is MODS, which additionally carries
            mods:identifier type="doi" and mods:nameIdentifier type="orcid".
          properties:
            dc: { $ref: '#/components/schemas/DublinCore' }
    DublinCore:
      type: object
      description: Simple Dublin Core (oai_dc). Elements are repeatable; xml:lang is present on this deployment.
      properties:
        title: { type: array, items: { type: string } }
        creator: { type: array, items: { type: string } }
        subject: { type: array, items: { type: string } }
        description: { type: array, items: { type: string } }
        publisher: { type: array, items: { type: string } }
        date: { type: array, items: { type: string } }
        type: { type: array, items: { type: string } }
        identifier:
          type: array
          items: { type: string }
          example: ['https://pure.york.ac.uk/portal/en/publications/d5ff166f-d255-4cab-9688-253729e80ee0']
        relation: { type: array, items: { type: string } }
        language: { type: array, items: { type: string } }
    OAIError:
      type: object
      description: 'OAI-PMH protocol error, returned with HTTP 200. badVerb and badArgument confirmed live.'
      properties:
        code:
          type: string
          enum: [badArgument, badResumptionToken, badVerb, cannotDisseminateFormat, idDoesNotExist, noRecordsMatch, noMetadataFormats, noSetHierarchy]
        message: { type: string }
security: []