OpenAPI pagination metadata: no standard for next/prev link representation

Implementing Pagination in OpenAPI

Because the OpenAPI Specification (OAS) does not provide a native keyword or object for pagination, the only way to ensure tooling compatibility and consistency is to define a custom reusable schema in the components/schemas section. This ensures that OpenAPI Generator and other tools treat the pagination metadata as a first-class typed object rather than an arbitrary map.

Recommended Pagination Structure

To maximize compatibility with Swagger UI and ReDoc without relying on vendor extensions, use a wrapper object. This avoids polluting the resource array and maintains type safety in strongly typed client languages.

components:
  schemas:
    PaginationMetadata:
      type: object
      properties:
        totalCount: 
          type: integer
          description: Total number of resources available (optional).
        pageSize: 
          type: integer
        currentPage: 
          type: integer
        links:
          type: object
          properties:
            next: { type: string, format: uri }
            prev: { type: string, format: uri }
            first: { type: string, format: uri }
            last: { type: string, format: uri }

    PaginatedResponse:
      type: object
      properties:
        data: 
          type: array
          items: { $ref: '#/components/schemas/Resource' }
        pagination: 
          $ref: '#/components/schemas/PaginationMetadata'

Addressing Privacy and Navigation

Total Counts: To mitigate privacy concerns (such as revealing the exact size of a user database), totalCount should be optional. If omitted, clients can rely on the presence of the links.next URI to determine if more data exists, which is the standard approach for cursor-based pagination.

Link Representation: Standardizing links as a nested links object (following HATEOAS principles) is the most scalable method. By defining this as a shared component, you avoid duplicating the schema across every list endpoint in your API.

Verification and Implementation

• Tooling Check: Verify that your chosen structure generates a distinct PaginationMetadata class in your target language (e.g., Java, TypeScript) using OpenAPI Generator.
• Response Validation: Ensure the links.next value is a full URI or a relative path that the client can resolve against the base URL.

Diagnostic Detail Needed: Are you utilizing offset-based pagination (page numbers) or cursor-based pagination (opaque tokens)? This determines whether currentPage and totalCount are functionally useful or should be replaced by a nextCursor string.