openapi: 3.1.0
info:
  title: UNSWorks Repository REST API
  version: '7.0'
  summary: Institution-operated DSpace 7.0 REST/HAL API for the UNSW open-access institutional repository.
  description: |
    UNSWorks is the University of New South Wales open-access institutional repository. It runs
    DSpace 7.0 on UNSW's own infrastructure, under UNSW's own registrable domain
    (unsworks.unsw.edu.au, A record 54.253.215.118 — no vendor CNAME), and is administered by the
    UNSW Library (adminEmail lib.repository.alerts@unsw.edu.au, published in the repository's own
    OAI-PMH Identify response).

    OPERATOR: institution. The DSpace software is open source (LYRASIS); the deployment, the
    hostname, the handle prefix 1959.4 and the content are UNSW's. This is not a vendor tenancy —
    contrast a `<institution>.figshare.com` style host, which would be `tenant`.

    PROVENANCE: UNSW publishes no OpenAPI for this surface. Every path and response below was
    derived from live, unauthenticated probes performed on 2026-08-19; nothing is inferred from
    generic DSpace documentation. Paths that returned 401 unauthenticated are documented as such
    rather than omitted, because the gate is itself the finding.
  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: >-
    Host unsworks.unsw.edu.au is under the institution's own registrable domain unsw.edu.au and
    resolves to a UNSW-controlled A record, not a vendor CNAME. The OAI-PMH Identify response on
    the same host names the repository "UNSWorks Repository" with a unsw.edu.au admin contact.
  x-provenance:
    generated: '2026-08-19'
    method: probed
    source:
      - https://unsworks.unsw.edu.au/server/api
      - https://unsworks.unsw.edu.au/server/api/core/communities?size=2
      - https://unsworks.unsw.edu.au/server/api/core/collections?size=1
      - https://unsworks.unsw.edu.au/server/api/core/sites
      - https://unsworks.unsw.edu.au/server/api/core/metadataschemas?size=50
      - https://unsworks.unsw.edu.au/server/api/core/metadatafields/search/byFieldName?query=orcid
      - https://unsworks.unsw.edu.au/server/api/core/entitytypes?size=30
      - https://unsworks.unsw.edu.au/server/api/discover/search/objects?size=1
      - https://unsworks.unsw.edu.au/server/api/core/items/00000000-0000-0000-0000-000000000000
servers:
  - url: https://unsworks.unsw.edu.au/server/api
    description: UNSWorks production DSpace 7.0 REST/HAL server (institution-operated).
tags:
  - name: root
    description: Service entry point and HAL link index.
  - name: core
    description: Communities, collections, sites and the metadata registry.
  - name: discover
    description: Public discovery search over repository objects.
paths:
  /:
    get:
      tags: [root]
      operationId: getRoot
      summary: Repository service document
      description: >-
        Returns the DSpace HAL entry point, including dspaceName, dspaceVersion and the full
        _links index for every sub-resource. Verified 200 on 2026-08-19.
      responses:
        '200':
          description: Service document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RootServiceDocument'
              examples:
                unsworks:
                  summary: Live UNSWorks response (excerpt)
                  value:
                    dspaceUI: https://unsworks.unsw.edu.au
                    dspaceName: UNSWorks Repository
                    dspaceServer: https://unsworks.unsw.edu.au/server
                    dspaceVersion: DSpace 7.0
                    type: root
  /core/communities:
    get:
      tags: [core]
      operationId: listCommunities
      summary: List top-level and child communities
      description: Verified 200 unauthenticated on 2026-08-19.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Paged HAL collection of communities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityPage'
  /core/collections:
    get:
      tags: [core]
      operationId: listCollections
      summary: List collections
      description: Verified 200 unauthenticated on 2026-08-19.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Paged HAL collection of collections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HalPage'
  /core/sites:
    get:
      tags: [core]
      operationId: listSites
      summary: Repository site object
      description: Verified 200 unauthenticated on 2026-08-19.
      responses:
        '200':
          description: Paged HAL collection containing the single site object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HalPage'
  /core/metadataschemas:
    get:
      tags: [core]
      operationId: listMetadataSchemas
      summary: Metadata schema registry
      description: >-
        Returns the metadata schema prefixes registered in this repository. UNSWorks returns
        dc, eperson, dspace, dcterms, local, unsw, relation, person, project, organization,
        periodical, creativework, creativeworkseries, publicationissue, publicationvolume, ac,
        atmire and workflow. Verified 200 unauthenticated on 2026-08-19.
      parameters:
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Paged HAL collection of metadata schemas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HalPage'
  /core/metadatafields/search/byFieldName:
    get:
      tags: [core]
      operationId: searchMetadataFields
      summary: Search the metadata field registry by field name
      description: Verified 200 unauthenticated on 2026-08-19.
      parameters:
        - name: query
          in: query
          required: true
          description: Substring matched against schema, element and qualifier.
          schema:
            type: string
          example: orcid
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Paged HAL collection of matching metadata fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HalPage'
  /core/entitytypes:
    get:
      tags: [core]
      operationId: listEntityTypes
      summary: Configured entity types
      description: >-
        UNSWorks returns Publication, OrgUnit, Dataset, Journal, JournalVolume and JournalIssue.
        Note the absence of a Person entity type, which is why the registered person.identifier.orcid
        field is not evidenced as populated. Verified 200 unauthenticated on 2026-08-19.
      parameters:
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Paged HAL collection of entity types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HalPage'
  /core/items/{uuid}:
    get:
      tags: [core]
      operationId: getItem
      summary: Fetch a single item by UUID
      description: >-
        Item retrieval by UUID. Probed on 2026-08-19 with a non-existent UUID, which returned the
        documented 404 error envelope. NOTE the browse form of this resource
        (GET /core/items without a UUID) returns 401 unauthenticated.
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The item.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: No item with that UUID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Returned for the unbounded browse form of this resource on UNSWorks
            (GET /core/items?size=1 returned 401 unauthenticated on 2026-08-19).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /discover/search/objects:
    get:
      tags: [discover]
      operationId: searchObjects
      summary: Discovery search across repository objects
      description: >-
        Open, unauthenticated discovery search. This is the endpoint that makes UNSWorks usable
        without credentials, given that /core/items and /core/bitstreams are gated.
        Verified 200 unauthenticated on 2026-08-19.
      parameters:
        - name: query
          in: query
          required: false
          schema:
            type: string
        - name: dsoType
          in: query
          required: false
          schema:
            type: string
            examples: [item]
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Discovery search result envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HalPage'
components:
  parameters:
    Page:
      name: page
      in: query
      required: false
      description: Zero-based page index.
      schema:
        type: integer
        minimum: 0
        default: 0
    Size:
      name: size
      in: query
      required: false
      description: Page size.
      schema:
        type: integer
        minimum: 1
        default: 20
  schemas:
    RootServiceDocument:
      type: object
      description: DSpace HAL entry point, captured live from UNSWorks.
      properties:
        dspaceUI:
          type: string
          format: uri
        dspaceName:
          type: string
        dspaceServer:
          type: string
          format: uri
        dspaceVersion:
          type: string
        type:
          type: string
        _links:
          type: object
          additionalProperties:
            type: object
            properties:
              href:
                type: string
              templated:
                type: boolean
      required: [dspaceUI, dspaceName, dspaceServer, dspaceVersion, type, _links]
    HalPage:
      type: object
      description: Generic DSpace HAL paged envelope.
      properties:
        _embedded:
          type: object
        page:
          type: object
          properties:
            size:
              type: integer
            totalElements:
              type: integer
            totalPages:
              type: integer
            number:
              type: integer
        _links:
          type: object
    CommunityPage:
      allOf:
        - $ref: '#/components/schemas/HalPage'
        - type: object
          properties:
            _embedded:
              type: object
              properties:
                communities:
                  type: array
                  items:
                    $ref: '#/components/schemas/Community'
    Community:
      type: object
      properties:
        id:
          type: string
          format: uuid
        uuid:
          type: string
          format: uuid
        name:
          type: string
        handle:
          type: string
          description: CNRI handle under the UNSW prefix 1959.4.
          examples: ['1959.4/3']
        type:
          type: string
          const: community
        metadata:
          $ref: '#/components/schemas/MetadataMap'
      required: [uuid, name, handle, type]
    MetadataMap:
      type: object
      description: DSpace metadata map keyed by qualified field name.
      additionalProperties:
        type: array
        items:
          type: object
          properties:
            value:
              type: string
            language:
              type: [string, 'null']
            authority:
              type: [string, 'null']
            confidence:
              type: integer
            place:
              type: integer
          required: [value]
    Error:
      type: object
      description: Spring Boot error envelope as returned live by UNSWorks.
      properties:
        timestamp:
          type: string
        status:
          type: integer
        error:
          type: string
        message:
          type: string
        path:
          type: string
      required: [timestamp, status, error, path]