openapi: 3.1.0
info:
  title: Science Museum Group Collection Documents People API
  description: 'A JSONAPI-compliant REST API providing open access to the Science Museum Group''s collection of over 7 million objects, people, and documents across five UK museums: the Science Museum (London), the Science and Industry Museum (Manchester), the National Railway Museum (York), the National Science and Media Museum (Bradford), and Locomotion (Shildon). The API supports full-text search, filtering, and individual record retrieval with rich metadata, image references, and curatorial annotations.'
  version: 1.0.0
  contact:
    name: Science Museum Group Collections
    url: https://www.sciencemuseumgroup.org.uk/our-work/our-collection/using-our-collection-api
  license:
    name: Open Government License
    url: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
servers:
- url: https://collection.sciencemuseumgroup.org.uk
  description: Science Museum Group Collection API
tags:
- name: People
  description: People associated with the museum collections including makers, scientists, and historical figures
paths:
  /search/people:
    get:
      operationId: searchPeople
      summary: Search Collection People
      description: Search for people associated with the Science Museum Group collection, including scientists, engineers, makers, and historical figures. Supports filtering by birth place, birth date, death date, occupation, and geographical associations.
      tags:
      - People
      parameters:
      - name: q
        in: query
        description: Full-text search query term
        required: false
        schema:
          type: string
      - name: birth[place]
        in: query
        description: Filter by birth place
        required: false
        schema:
          type: string
      - name: birth[date]
        in: query
        description: Filter by birth date (year or year-month)
        required: false
        schema:
          type: string
      - name: death[date]
        in: query
        description: Filter by death date (year or year-month)
        required: false
        schema:
          type: string
      - name: occupation
        in: query
        description: Filter by occupation or profession
        required: false
        schema:
          type: string
      - name: places
        in: query
        description: Filter by geographical association
        required: false
        schema:
          type: string
      - name: images
        in: query
        description: Filter to people with available images
        required: false
        schema:
          type: boolean
      - name: page[number]
        in: query
        description: Zero-indexed page number
        required: false
        schema:
          type: integer
          default: 0
      - name: page[size]
        in: query
        description: Results per page (max 100)
        required: false
        schema:
          type: integer
          maximum: 100
          default: 50
      responses:
        '200':
          description: Successful people search response
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PeopleSearchResponse'
  /people/{id}:
    get:
      operationId: getPerson
      summary: Get Collection Person
      description: Retrieve a single person record by its unique identifier. Returns the full JSONAPI resource record including biographical information, image references, and relationships to collection objects and documents.
      tags:
      - People
      parameters:
      - name: id
        in: path
        description: Unique person identifier
        required: true
        schema:
          type: string
        example: cp22644
      responses:
        '200':
          description: Successful person retrieval
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PersonResponse'
        '404':
          description: Person not found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CollectionResource:
      type: object
      description: A JSONAPI resource item in the collection
      properties:
        id:
          type: string
          description: Unique resource identifier
        type:
          type: string
          enum:
          - objects
          - people
          - documents
          description: Resource type
        attributes:
          type: object
          description: Resource attributes and metadata
          properties:
            name:
              type: object
              description: Name information with primary and alternate names
            summary:
              type: string
              description: Brief summary of the item
            description:
              type: string
              description: Detailed description
            date:
              type: object
              description: Date information including earliest and latest dates
            images:
              type: object
              description: Image references and media information
            museums:
              type: array
              description: Museums where the item is held
              items:
                type: string
            on_display:
              type: boolean
              description: Whether the item is currently on public display
            location:
              type: object
              description: Gallery or storage location information
        relationships:
          type: object
          description: Related resources
          properties:
            makers:
              type: object
              description: People or organizations who made or created the item
            people:
              type: object
              description: People associated with this item
            documents:
              type: object
              description: Related documents
        links:
          type: object
          properties:
            self:
              type: string
              format: uri
              description: Canonical URL for this resource
    PersonResponse:
      type: object
      description: JSONAPI response for a single person record
      properties:
        data:
          $ref: '#/components/schemas/CollectionResource'
    ErrorResponse:
      type: object
      description: JSONAPI error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
                description: HTTP status code
              title:
                type: string
                description: Error title
              detail:
                type: string
                description: Error detail message
    PeopleSearchResponse:
      type: object
      description: JSONAPI search response for collection people
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CollectionResource'
        meta:
          type: object
          properties:
            total:
              type: integer
              description: Total number of matching people
        links:
          $ref: '#/components/schemas/PaginationLinks'
    PaginationLinks:
      type: object
      description: JSONAPI pagination links
      properties:
        first:
          type: string
          format: uri
          description: Link to the first page
        last:
          type: string
          format: uri
          description: Link to the last page
        prev:
          type: string
          format: uri
          nullable: true
          description: Link to the previous page
        next:
          type: string
          format: uri
          nullable: true
          description: Link to the next page