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

Unresolved decision on pagination metadata in OpenAPI

The OpenAPI Specification does not define a model for pagination metadata. Service designers must decide how to embed next, prev, first, and last links, as well as total count and page size, in the response body.

Constraints include tooling compatibility (Swagger UI, ReDoc, OpenAPI Generator), privacy (exposing total counts may reveal data volume), and consistency across multiple APIs. Vendor extensions such as x-pagination exist but are not governed by the core spec and may break client generation.

To move forward, we need a decision on a shared pagination contract that balances tooling support, privacy, and developer ergonomics.

Specific questions

• What structure should a pagination metadata object adopt to be recognized by major OpenAPI tooling without relying on vendor extensions?
• Should total counts be mandatory, optional, or omitted to mitigate privacy concerns while enabling efficient client navigation?
• How can we standardize link representation (e.g., links.next, links.prev) across services to avoid duplicated schema definitions?