openapi: 3.1.0
info:
title: UNSWorks Repository OAI-PMH Interface
version: '2.0'
summary: Institution-operated OAI-PMH 2.0 metadata harvesting endpoint for UNSWorks.
description: |
OAI-PMH 2.0 harvesting interface for the UNSW open-access institutional repository, served
from UNSW's own host. The Identify response names the repository "UNSWorks Repository",
declares repositoryIdentifier unsworks.library.unsw.edu.au, an earliestDatestamp of
2007-11-06 and an admin contact of lib.repository.alerts@unsw.edu.au.
OPERATOR: institution. OAI-PMH is one of the few machine-readable surfaces a university
genuinely operates itself even when the repository software came from somewhere else — the
protocol, the base URL, the sets and the records are all under UNSW's control.
This is also the institution's strongest `education`-regime domain-standard conformance:
OAI-PMH 2.0, live, on their own host, exposing twelve metadata formats.
PROVENANCE: UNSW publishes no OpenAPI for this surface. Every verb, parameter and error code
below was exercised live on 2026-08-19; none is copied from the OAI-PMH specification without
being confirmed against this endpoint.
contact:
name: UNSW Library — UNSWorks Repository
email: lib.repository.alerts@unsw.edu.au
url: https://unsworks.unsw.edu.au/
x-operator: institution
x-operator-evidence: >-
baseURL declared inside the endpoint's own Identify response is
https://unsworks.unsw.edu.au/oai/request, under the institution's registrable domain, with a
unsw.edu.au adminEmail and the UNSW handle prefix 1959.4 in its sample identifier.
x-provenance:
generated: '2026-08-19'
method: probed
source:
- https://unsworks.unsw.edu.au/oai/request?verb=Identify
- https://unsworks.unsw.edu.au/oai/request?verb=ListMetadataFormats
- https://unsworks.unsw.edu.au/oai/request?verb=ListSets
- https://unsworks.unsw.edu.au/oai/request?verb=ListIdentifiers&metadataPrefix=oai_dc
- https://unsworks.unsw.edu.au/oai/request?verb=ListRecords&metadataPrefix=oai_dc
- https://unsworks.unsw.edu.au/oai/request?verb=GetRecord&metadataPrefix=oai_dc&identifier=oai:unsworks.library.unsw.edu.au:1959.4/60912
- https://unsworks.unsw.edu.au/oai/request?verb=Bogus
- https://unsworks.unsw.edu.au/oai/request?verb=GetRecord
servers:
- url: https://unsworks.unsw.edu.au/oai
description: UNSWorks OAI-PMH base (institution-operated).
tags:
- name: oai-pmh
description: OAI-PMH 2.0 verbs, all exercised live against this endpoint.
paths:
/request:
get:
tags: [oai-pmh]
operationId: oaiRequest
summary: OAI-PMH 2.0 request
description: |
Single verb-dispatched endpoint. All six OAI-PMH verbs were confirmed to return HTTP 200
with a well-formed OAI-PMH envelope on 2026-08-19:
- `Identify` — repositoryName "UNSWorks Repository", protocolVersion 2.0,
granularity YYYY-MM-DDThh:mm:ssZ, deletedRecord transient.
- `ListMetadataFormats` — twelve prefixes: uketd_dc, qdc, didl, mods, ore, mets, oai_dc,
rdf, marc, xoai, dim, etdms.
- `ListSets` — community and collection sets under the UNSW handle prefix
(com_1959.4_*, col_1959.4_*).
- `ListIdentifiers`, `ListRecords`, `GetRecord` — confirmed with metadataPrefix=oai_dc;
a real identifier returned by this endpoint is
oai:unsworks.library.unsw.edu.au:1959.4/60912.
Errors are returned in-band as an `<error code="...">` element with HTTP 200, per the
OAI-PMH specification; the two confirmed codes are documented under responses.
parameters:
- name: verb
in: query
required: true
description: OAI-PMH verb.
schema:
type: string
enum:
- Identify
- ListMetadataFormats
- ListSets
- ListIdentifiers
- ListRecords
- GetRecord
- name: metadataPrefix
in: query
required: false
description: >-
Required for ListIdentifiers, ListRecords and GetRecord. Confirmed supported values on
this endpoint: uketd_dc, qdc, didl, mods, ore, mets, oai_dc, rdf, marc, xoai, dim, etdms.
schema:
type: string
enum: [uketd_dc, qdc, didl, mods, ore, mets, oai_dc, rdf, marc, xoai, dim, etdms]
- name: identifier
in: query
required: false
description: OAI identifier, required for GetRecord.
schema:
type: string
example: 'oai:unsworks.library.unsw.edu.au:1959.4/60912'
- name: set
in: query
required: false
description: Set spec, e.g. com_1959.4_3 or col_1959.4_14.
schema:
type: string
- name: from
in: query
required: false
description: Lower datestamp bound. Earliest datestamp in this repository is 2007-11-06T00:00:00Z.
schema:
type: string
- name: until
in: query
required: false
description: Upper datestamp bound.
schema:
type: string
- name: resumptionToken
in: query
required: false
description: Flow-control token for continuing a list request.
schema:
type: string
responses:
'200':
description: >-
OAI-PMH envelope. Per the protocol this status is also used for protocol-level errors,
which appear as an <error code="..."> element. Confirmed codes on this endpoint:
badVerb ("Illegal verb") and badArgument ("GetRecord verb requires the use of the
parameters - identifier and metadataPrefix").
content:
application/xml:
schema:
$ref: '#/components/schemas/OaiPmhEnvelope'
components:
schemas:
OaiPmhEnvelope:
type: object
description: >-
XML document rooted at OAI-PMH in namespace http://www.openarchives.org/OAI/2.0/. Modelled
structurally here because OpenAPI has no native XSD reference; the authoritative schema is
http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd, which this endpoint declares in its own
xsi:schemaLocation.
properties:
responseDate:
type: string
format: date-time
request:
type: string
format: uri
error:
type: object
properties:
code:
type: string
enum:
- badVerb
- badArgument
- badResumptionToken
- cannotDisseminateFormat
- idDoesNotExist
- noRecordsMatch
- noMetadataFormats
- noSetHierarchy
message:
type: string
Identify:
$ref: '#/components/schemas/Identify'
Identify:
type: object
description: Captured live from this endpoint on 2026-08-19.
properties:
repositoryName:
type: string
examples: ['UNSWorks Repository']
baseURL:
type: string
format: uri
examples: ['https://unsworks.unsw.edu.au/oai/request']
protocolVersion:
type: string
const: '2.0'
adminEmail:
type: string
format: email
examples: ['lib.repository.alerts@unsw.edu.au']
earliestDatestamp:
type: string
format: date-time
examples: ['2007-11-06T00:00:00Z']
deletedRecord:
type: string
examples: ['transient']
granularity:
type: string
examples: ['YYYY-MM-DDThh:mm:ssZ']
repositoryIdentifier:
type: string
examples: ['unsworks.library.unsw.edu.au']
required: [repositoryName, baseURL, protocolVersion, adminEmail, earliestDatestamp]