From dd92164592bd93ed28c20c427323bc49edddb78a Mon Sep 17 00:00:00 2001
From: "intility-claude[bot]"
 <2458755+intility-claude[bot]@users.noreply.github.com>
Date: Wed, 15 Apr 2026 11:26:13 +0000
Subject: [PATCH] docs: auto-generated docs for
 intility/Intility.JsonApiToolkit#116

Generated by Claude Auto Docs workflow.
Source PR: https://github.com/intility/Intility.JsonApiToolkit/pull/116
---
 docs/docs/getting-started.md |  1 +
 docs/docs/querying.md        |  5 ++--
 docs/docs/security.md        | 47 +++++++++++++++++++++++++++++++++++-
 3 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
index 0c069d5..51abf43 100644
--- a/docs/docs/getting-started.md
+++ b/docs/docs/getting-started.md
@@ -50,6 +50,7 @@ dotnet add package Intility.JsonApiToolkit
        options.MaxFilterDepth = 5;                // Default: 3
        options.MaxPageSize = 200;                 // Default: 100
        options.DefaultPageSize = 25;              // Default: 10
+       options.StrictPagination = true;           // Default: false
        options.EnableDatabaseProjection = true;   // Default: false
    });
    ```
diff --git a/docs/docs/querying.md b/docs/docs/querying.md
index 6fd21bb..0a36591 100644
--- a/docs/docs/querying.md
+++ b/docs/docs/querying.md
@@ -32,9 +32,10 @@ JsonApiToolkit provides robust support for JSON:API querying, including filterin
   The `sort` parameter allows multiple sort criteria. Prefixing a field with a minus (`-`) indicates descending order.
   - Example: `GET /api/books?sort=title,-publishedDate`
 
-- **Pagination (`page[number]` and `page[size]`):**  
+- **Pagination (`page[number]` and `page[size]`):**
   Control how many results are returned and which page to view.
   - Example: `GET /api/books?page[number]=2&page[size]=5`
+  - By default, invalid pagination values (page number less than 1, page size exceeding `MaxPageSize`) are silently clamped to valid ranges. Enable `StrictPagination` to return 400 errors instead (see [Security](security.md#strict-pagination)).
 
 - **Inclusion (`include`):**  
   Specify which related resources should be included in the response.
@@ -121,7 +122,7 @@ JsonApiToolkit enforces the following query limits to ensure predictable perform
 | Max Filter Depth | 3 | Maximum nesting of filter groups |
 | Max Filter Value Length | 1000 | Maximum characters per filter value |
 | Max Include Depth | 3 | Maximum include path depth (e.g., `author.posts.comments`) |
-| Max Page Size | 100 | Maximum items per page (silently clamped) |
+| Max Page Size | 100 | Maximum items per page (clamped or rejected based on `StrictPagination`) |
 
 These limits are configurable via `JsonApiOptions`. See the [Security](security.md#query-complexity-limits) documentation for configuration details.
 
diff --git a/docs/docs/security.md b/docs/docs/security.md
index 6b6c778..9d2e5f9 100644
--- a/docs/docs/security.md
+++ b/docs/docs/security.md
@@ -96,6 +96,7 @@ builder.Services.AddJsonApiToolkit(options => {
     options.MaxIncludeDepth = 3;       // Max include path depth (default: 3)
     options.MaxPageSize = 100;         // Max page size, clamped (default: 100)
     options.DefaultPageSize = 10;      // Default when not specified (default: 10)
+    options.StrictPagination = false;  // Reject invalid pagination (default: false)
 });
 ```
 
@@ -108,7 +109,7 @@ builder.Services.AddJsonApiToolkit(options => {
 | `MaxFilterDepth` | Returns 400 Bad Request |
 | `MaxFilterValueLength` | Returns 400 Bad Request |
 | `MaxIncludeDepth` | Returns 400 Bad Request |
-| `MaxPageSize` | Silently clamped to max value |
+| `MaxPageSize` | Clamped (default) or 400 Bad Request (`StrictPagination`) |
 
 ### Error Response
 
@@ -168,6 +169,50 @@ When filtering on a non-allowed relationship:
 > [!NOTE]
 > This validation only applies when `[AllowedIncludes]` is present. Without the attribute, all filter paths are allowed.
 
+## Strict Pagination
+
+By default, JsonApiToolkit silently clamps invalid pagination parameters to valid ranges for backwards compatibility. Enable `StrictPagination` to return 400 Bad Request errors instead.
+
+### Configuration
+
+```csharp
+builder.Services.AddJsonApiToolkit(options => {
+    options.StrictPagination = true;
+});
+```
+
+### Behavior
+
+When `StrictPagination` is enabled, the following values are rejected with 400 Bad Request:
+
+- `page[number]` less than 1 (e.g., `page[number]=0` or `page[number]=-5`)
+- `page[size]` less than 1 (e.g., `page[size]=0` or `page[size]=-10`)
+- `page[size]` exceeding `MaxPageSize` (e.g., `page[size]=200` when `MaxPageSize=100`)
+
+When disabled (default), these values are silently clamped:
+
+- `page[number]` less than 1 becomes 1
+- `page[size]` exceeding `MaxPageSize` becomes `MaxPageSize`
+
+### Error Response
+
+```json
+{
+  "errors": [{
+    "status": "400",
+    "code": "INVALID_PAGE_SIZE",
+    "title": "Invalid page size",
+    "detail": "Page size '200' exceeds maximum allowed size of 100. Reduce page size or configure a higher limit via JsonApiOptions.MaxPageSize.",
+    "source": { "parameter": "page[size]" },
+    "meta": {
+      "value": 200,
+      "max": 100,
+      "configKey": "JsonApiOptions.MaxPageSize"
+    }
+  }]
+}
+```
+
 ## DoS Protection
 
 The query complexity limits protect against several denial-of-service attack vectors: