openapi: 3.2.0
info:
  title: Penn Libraries Franklin — JSON Catalog API
  version: '1.0'
  description: Machine-readable JSON:API surface of Franklin, the University of Pennsylvania Libraries discovery catalog at find.library.upenn.edu. Franklin is a Blacklight application operated by Penn Libraries on a University of Pennsylvania host; every Blacklight page has a `.json` twin, which makes the catalog harvestable without a vendor contract. Penn Libraries publishes an open-metadata policy that explicitly permits reuse of this bibliographic data. This contract was DERIVED by probing live responses — Penn publishes no OpenAPI for it.
  contact:
    name: Penn Libraries
    url: https://www.library.upenn.edu/
  termsOfService: https://www.library.upenn.edu/about/policies/open-metadata
  x-operator: institution
  x-operator-entity: University of Pennsylvania (Penn Libraries)
  x-software: Blacklight
  x-provenance:
    generated: '2026-08-19'
    method: derived
    source: https://find.library.upenn.edu/catalog.json?q=penn
    note: Derived from live probes on 2026-08-19. /catalog.json returned HTTP 200 JSON:API with links, meta.pages (total_count 388604) and data[]; /catalog/{id}.json returned HTTP 200 for an id taken from that result set; an unmatched query returned HTTP 200 with an empty data[] rather than a 404.
servers:
- url: https://find.library.upenn.edu
  description: Franklin, the Penn Libraries catalog
tags:
- name: Catalog
  description: Bibliographic search and record retrieval.
paths:
  /catalog.json:
    get:
      tags:
      - Catalog
      summary: Search the catalog
      operationId: searchCatalog
      description: Paginated JSON:API search over Penn Libraries bibliographic records. Facet parameters follow Blacklight's `f[<facet_field>][]` convention.
      parameters:
      - name: q
        in: query
        description: Search query.
        required: false
        schema:
          type: string
      - name: search_field
        in: query
        description: Named search field, e.g. all_fields, title_search, author_search.
        required: false
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 10
      - name: sort
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: JSON:API search result. An unmatched query returns 200 with empty data[].
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
  /catalog/{id}.json:
    get:
      tags:
      - Catalog
      summary: Retrieve one bibliographic record
      operationId: getCatalogRecord
      parameters:
      - name: id
        in: path
        required: true
        description: Alma MMS id as exposed by search results, e.g. 9977415244603681.
        schema:
          type: string
      responses:
        '200':
          description: JSON:API document for a single record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordDocument'
        '404':
          description: No record with that identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RecordDocument:
      type: object
      properties:
        links:
          type: object
        data:
          $ref: '#/components/schemas/Resource'
        included:
          type: array
          items:
            type: object
    Error:
      type: object
      properties:
        status:
          type: integer
        error:
          type: string
    SearchResult:
      type: object
      properties:
        links:
          type: object
          properties:
            self:
              type: string
              format: uri
            next:
              type: string
              format: uri
            last:
              type: string
              format: uri
        meta:
          type: object
          properties:
            pages:
              type: object
              properties:
                current_page:
                  type: integer
                next_page:
                  type:
                  - integer
                  - 'null'
                prev_page:
                  type:
                  - integer
                  - 'null'
                total_pages:
                  type: integer
                limit_value:
                  type: integer
                offset_value:
                  type: integer
                total_count:
                  type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        included:
          type: array
          items:
            type: object
    Resource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        attributes:
          type: object
        links:
          type: object