University of York OAI PMH API

openapi: 3.2.0
info:
  title: University of York Research Portal OAI PMH API
  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.
  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
servers:
- url: https://pure.york.ac.uk/ws
  description: University of York research portal OAI-PMH base
security: []
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 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:
  schemas:
    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
    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'
    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
    RecordHeader:
      type: object
      properties:
        identifier:
          type: string
        datestamp:
          type: string
          format: date-time
        setSpec:
          type: array
          items:
            type: string
    Set:
      type: object
      properties:
        setSpec:
          type: string
          example: publications:all
        setName:
          type: string
          example: PURE publications
    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
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=...