Penn Libraries Franklin Catalog — JSON API

openapi: 3.0.3
info:
  title: Penn Libraries Franklin Catalog — JSON 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:
    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, nullable: true }
                prev_page: { type: integer, nullable: true }
                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 }
    RecordDocument:
      type: object
      properties:
        links: { type: object }
        data: { $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 }
    Error:
      type: object
      properties:
        status: { type: integer }
        error: { type: string }