Collection Response Shaping Prompt for List Endpoints

This prompt is designed for API developers and backend engineers who need to standardize the response shape of list endpoints. The primary job-to-be-done is transforming a raw, unstructured list of items from a model or an upstream service into a predictable, application-ready collection envelope. The ideal user is someone integrating AI-generated or AI-processed data into an existing API contract, where downstream clients expect consistent items arrays, total_count fields, and HATEOAS-style links for pagination. You should use this prompt when the core logic of item generation or retrieval is handled, but the final structural wrapping must be guaranteed before the response is serialized and sent over the wire.

This prompt is not a replacement for your database query or your application's actual pagination logic. Do not use it to calculate real total_count values from a live database or to enforce business-logic-level authorization on individual items. Its strength is in shaping a given set of items into a consistent contract. The required context includes the raw items payload, the desired pagination metadata (offset, limit, total), and the base URL for link generation. The prompt is most effective when the upstream item schema is already well-defined; it will enforce that schema on every item in the collection, making it a powerful guardrail against partial or malformed objects leaking into the array. If your primary challenge is generating the items themselves or performing complex aggregation, use a dedicated generation or analysis prompt first, and pipe the result into this shaping prompt as a final assembly step.

Before implementing, identify the failure modes that matter most for your API consumers. If an empty collection should return a 200 OK with an empty items array rather than a 404, this prompt must be explicitly instructed to do so. If a single-item collection must still be wrapped in an array, validate that the output never accidentally flattens the structure. The next step is to copy the prompt template, replace the bracketed placeholders with your specific schema and endpoint details, and run it against a set of test cases that include empty sets, single items, and full pages. Pair this prompt with a JSON Schema validator in your API gateway or middleware to catch structural regressions before they reach a client.

This prompt template is designed to be copied directly into your prompt management system, IDE, or orchestration layer. It takes raw list data and context about the API's pagination strategy and produces a structured collection envelope with items, metadata, and navigation links. The template uses square-bracket placeholders that you must replace with actual values before sending the prompt to a model. Each placeholder represents a variable input that changes per request—such as the items array, pagination parameters, or output schema constraints.

textCopy
You are an API response formatter. Your task is to wrap a collection of items into a standardized list endpoint response envelope.

## Input Data
- Items array: [ITEMS]
- Pagination strategy: [PAGINATION_STRATEGY]
- Current offset/page: [CURRENT_PAGE]
- Page size/limit: [PAGE_SIZE]
- Total item count: [TOTAL_COUNT]
- Base URL for link generation: [BASE_URL]
- Current request path: [REQUEST_PATH]

## Output Schema
Produce a JSON object matching this structure:
{
  "data": {
    "items": [ITEM_SCHEMA],
    "total_count": integer,
    "page": integer | null,
    "page_size": integer | null,
    "offset": integer | null,
    "limit": integer | null
  },
  "links": {
    "self": string,
    "next": string | null,
    "prev": string | null,
    "first": string | null,
    "last": string | null
  },
  "meta": {
    "request_id": string | null,
    "timestamp": string (ISO 8601),
    "collection_size": integer
  }
}

## Constraints
- Every item in the `items` array must conform to [ITEM_SCHEMA]. If an item is missing a required field, omit it and include a warning in `meta.warnings`.
- For empty collections, `items` must be an empty array `[]`, not null or missing.
- `total_count` must equal the length of the full unfiltered collection, not just the current page.
- Generate `links` based on [PAGINATION_STRATEGY]:
  - If offset-based: use `offset` and `limit` query parameters.
  - If cursor-based: use `cursor` query parameter with opaque cursor values derived from item IDs.
  - If page-based: use `page` and `per_page` query parameters.
- Set `next` to null when on the last page or when `total_count` indicates no more items.
- Set `prev` to null when on the first page.
- `meta.timestamp` must be the current time in ISO 8601 format.
- Do not include any fields outside the specified schema.
- Do not wrap the response in an explanatory message. Return only the JSON object.

## Examples
Input: 3 items, offset=0, limit=10, total_count=3
Expected: items array with 3 items, next=null, prev=null, total_count=3

Input: 0 items, offset=0, limit=10, total_count=0
Expected: items=[], next=null, prev=null, total_count=0

Input: 5 items, offset=10, limit=5, total_count=27
Expected: items array with 5 items, next link present, prev link present, total_count=27

## Risk Level
[RISK_LEVEL]

## Additional Context
[CONTEXT]

To adapt this template for your application, replace each square-bracket placeholder with concrete values at runtime. [ITEMS] should contain the serialized array of records for the current page. [ITEM_SCHEMA] should describe the expected shape of each item—either as a JSON Schema fragment or a natural language description of required fields and types. [PAGINATION_STRATEGY] must be one of offset, cursor, or page to control link generation logic. [RISK_LEVEL] should be set to low, medium, or high to adjust the model's caution; for high-risk contexts such as financial or healthcare data, add explicit instructions to refuse generation if item schemas are violated. [CONTEXT] can include additional business rules, such as maximum page size limits or tenant isolation requirements. After substitution, validate the prompt by running it against known test cases—empty collections, single-item collections, and boundary pages—before deploying to production.

The Collection Response Shaping Prompt is designed to sit behind an API endpoint that aggregates data from a model and returns it in a predictable envelope. The prompt itself is stateless; the application layer must supply the raw items, pagination metadata, and any link generation logic. The model's job is strictly to assemble these inputs into the target envelope structure, enforce item schema consistency, and handle edge cases like empty collections or single-item lists. Do not rely on the model to calculate total_count or generate accurate next/prev links from scratch—these values should be computed by your application and passed into the prompt as [CONTEXT] variables.

Wire the prompt into a service function that accepts a list of items, a pagination state object, and a base URL for link construction. Before calling the model, validate that all items conform to the expected item schema at the application level. The model should receive pre-validated items and focus on envelope assembly, not data cleaning. After receiving the model's JSON response, run a strict post-generation validator that checks: (1) the root object contains items, total_count, and links keys; (2) items is an array and every element matches the item schema; (3) total_count is a non-negative integer matching the application's known count; (4) links.self, links.next, and links.prev are either valid URLs or null; and (5) empty collections produce items: [] with links.next and links.prev set to null. If validation fails, retry once with the validation error message appended to the prompt as a correction hint. If the retry also fails, log the failure, return a 500 error with a fallback envelope, and alert the on-call channel.

For model selection, prefer models with strong JSON mode and schema-following behavior (e.g., GPT-4o with structured outputs, Claude 3.5 Sonnet with tool use set to a no-op function returning the envelope schema). Avoid models that struggle with consistent link generation or that hallucinate pagination values. In high-throughput scenarios, consider caching the system prompt prefix and batching multiple collection requests into a single model call where each request is a separate envelope assembly task. Implement request ID and trace ID propagation through the prompt context so that every generated envelope can be correlated back to the originating API request in your observability platform. Finally, add an eval suite with golden test cases covering: empty collection, single item, full page, last page (where next is null), and malformed input items. Run these evals on every prompt change before deployment.