Bounding Limit and Offset Query Parameters in Fastify Route Schemas

Question

Goal: Validate limit and offset query parameters in Fastify route schemas so large dataset endpoints cannot return unbounded result sets.

Fastify does not enforce a global maximum page size. Each route must declare its own limit cap, or use shared schema composition to apply the same minimum, maximum, and default values across multiple endpoints. Offset-based pagination scans and discards skipped rows, which degrades as the offset grows unless the underlying table and query plan support it.

Uncertainty: whether to centralize the pagination schema in Fastify version 4 using schema composition, or define limit and offset constraints individually on each route. It is also unclear whether a single maximum limit fits all endpoints or whether some routes need a higher cap.

Should limit and offset constraints be defined once with Fastify schema composition and referenced across routes, or declared per route?
What is a safe default maximum limit for offset-based pagination on large tables without indexes?
Does Fastify version 4 Ajv validation reject out-of-range limit and offset values with a 400 before the handler runs?

Tasadduq Burney · Answer

Direct answer
Use Fastify schema composition when endpoints share the same page-size cap; declare limit and offset per route when any endpoint needs a different bound. Fastify 4 validates schema.querystring with Ajv before the handler runs, so out-of-range values return 400 and the handler is not executed. Fastify does not impose a global maximum page size.
Confirmed facts versus likely explanation
Confirmed: route schemas are compiled at startup; unresolved $ref references fail startup. Ajv default values are not applied automatically unless the Fastify Ajv instance is configured with useDefaults. Offset-based pagination scans and discards skipped rows, so cost grows with the offset even when limit is bounded.
Likely explanation, mark for review: a conservative shared maximum such as 25 or 50 is a reasonable starting point for public list endpoints on large unindexed tables, but the correct cap is application-specific and not defined by Fastify. Exports or admin endpoints may require a higher limit.
Steps for this case

Register the shared schema before routes:

fastify.addSchema({
  $id: 'pagination',
  type: 'object',
  properties: {
    limit: { type: 'integer', minimum: 1, maximum: 100, default: 25 },
    offset: { type: 'integer', minimum: 0, default: 0 }
  }
});

Reference it in route schemas:

fastify.get('/items', {
  schema: {
    querystring: {
      type: 'object',
      properties: {
        limit: { $ref: 'pagination#/properties/limit' },
        offset: { $ref: 'pagination#/properties/offset' }
      }
    }
  }
}, handler);

Verify pre-handler rejection:

curl -i "http://localhost:3000/items?limit=200"
Expect a 400 response; confirm the handler does not run.
Missing diagnostic detail
Do any endpoints require a limit higher than the shared cap? This determines whether one composed schema is enough or whether per-route declarations are necessary.

Bounding Limit and Offset Query Parameters in Fastify Route Schemas

1 answer

Direct answer

Confirmed facts versus likely explanation

Steps for this case

Missing diagnostic detail

Your perspective belongs here.

0 question comments