Updated documentation

Author: sdangol

aidlc-docs/audit.md

@@ -1537,3 +1537,60 @@ app.post('/users', handler, {
 **Status**: Complete - all tests use spies to verify validation execution
 
 ---
+
+## Update Examples and Documentation
+**Timestamp**: 2025-11-11T20:52:47.478Z
+**User Input**: "Update the changes made in examples/snippets/event-handler/rest with the latest. Update the docs in docs/features/event-handler/rest.md"
+**AI Response**: Updating examples and documentation for validation feature
+**Context**: Adding validation examples and documentation
+
+---
+
+## Examples and Documentation Updated
+**Timestamp**: 2025-11-11T20:55:00.000Z
+**AI Response**: Successfully updated examples and documentation for validation feature
+**Context**: Updated to use new validation option API instead of middleware
+
+**Changes Made**:
+1. ✅ Updated `validation_basic.ts` - Use validation option instead of middleware
+2. ✅ Updated `validation_query_headers.ts` - Use validation option
+3. ✅ Updated `validation_error_handling.ts` - Use validation option
+4. ✅ Updated `validation_README.md` - Document new API and configuration
+5. ✅ Updated `docs/features/event-handler/rest.md` - Replace "coming soon" with full documentation
+6. ✅ Added validation section with examples and supported libraries
+
+**Documentation Sections Added**:
+- Basic validation with Zod
+- Validating multiple components
+- Error handling
+- Supported schema libraries table
+- Development mode details
+
+**Status**: Complete - examples and documentation updated with new validation API
+
+---
+
+## Fix Examples - Use Experimental Import
+**Timestamp**: 2025-11-11T21:02:08.057Z
+**User Input**: "Still use '@aws-lambda-powertools/event-handler/experimental-rest' for imports. Remove the validation_README.md file, the snippets folder only contains code snippets. Remove the part about customizing error using `onError`, it doesn't exist. Remove the part about supported schema libraries, development mode."
+**AI Response**: Fixing examples to use experimental import and removing unnecessary content
+**Context**: Simplifying examples and documentation
+
+---
+
+## Examples and Docs Fixed
+**Timestamp**: 2025-11-11T21:03:00.000Z
+**AI Response**: Fixed examples to use experimental import and simplified documentation
+**Context**: Removed unnecessary content, kept only code snippets
+
+**Changes Made**:
+1. ✅ Updated all examples to use `@aws-lambda-powertools/event-handler/experimental-rest`
+2. ✅ Removed `validation_README.md` file
+3. ✅ Removed `onError` customization section from docs (doesn't exist)
+4. ✅ Removed supported schema libraries table from docs
+5. ✅ Removed development mode section from docs
+6. ✅ Simplified validation_error_handling.ts to just show schema usage
+
+**Status**: Complete - examples use experimental import, documentation simplified
+
+---

docs/features/event-handler/rest.md

@@ -12,7 +12,7 @@ Event handler for Amazon API Gateway REST <!-- and HTTP APIs, Application Loader
 ## Key Features
 
 * Lightweight routing to reduce boilerplate for API Gateway REST (HTTP API, ALB and Lambda Function URLs coming soon)
-* Built-in middleware engine for request/response transformation (validation coming soon).
+* Built-in middleware engine for request/response transformation and validation
 * Works with micro function (one or a few routes) and monolithic functions (see [Considerations](#considerations)).
 
 ## Getting started
@@ -120,11 +120,42 @@ If you need to accept multiple HTTP methods in a single function, or support an
 
 ### Data validation
 
-!!! note "Coming soon"
+You can validate incoming requests and outgoing responses using any schema library that implements the [Standard Schema](https://standardschema.dev){target="_blank"} specification, such as Zod, Valibot, or ArkType.
+
+The validation feature automatically validates request components (body, headers, path parameters, query parameters) before your handler executes, and optionally validates responses after your handler completes.
+
+#### Basic validation
+
+Use the `validation` option when defining routes to specify which components to validate:
+
+=== "validation_basic.ts"
+
+    ```typescript hl_lines="17 20-22 26-31"
+    --8<-- "examples/snippets/event-handler/rest/validation_basic.ts"
+    ```
+
+#### Validating multiple components
 
-We plan to add built-in support for request and response validation using [Standard Schema](https://standardschema.dev){target="_blank"} in a future release. For the time being, you can use any validation library of your choice in your route handlers or middleware.
+You can validate multiple request components simultaneously:
 
-Please [check this issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/4516) for more details and examples, and add 👍 if you would like us to prioritize it.
+=== "validation_query_headers.ts"
+
+    ```typescript hl_lines="40-51"
+    --8<-- "examples/snippets/event-handler/rest/validation_query_headers.ts"
+    ```
+
+#### Error handling
+
+Validation errors are automatically handled by the router:
+
+- **Request validation failures** return HTTP 422 (Unprocessable Entity) with `RequestValidationError`
+- **Response validation failures** return HTTP 500 (Internal Server Error) with `ResponseValidationError`
+
+=== "validation_error_handling.ts"
+
+    ```typescript hl_lines="6-10"
+    --8<-- "examples/snippets/event-handler/rest/validation_error_handling.ts"
+    ```
 
 ### Accessing request details
 

examples/snippets/event-handler/rest/validation_README.md

@@ -1,5 +1,4 @@
 import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
-import { validation } from '@aws-lambda-powertools/event-handler/experimental-rest/middleware';
 import { z } from 'zod';
 
 const app = new Router();
@@ -19,40 +18,32 @@ const userResponseSchema = z.object({
 });
 
 // Validate request body
-app.post('/users', {
-  middleware: [validation({ req: { body: createUserSchema } })],
-}, async (reqCtx) => {
-  const body = reqCtx.req.body;
-  // body is typed as { name: string; email: string; age?: number }
-  
+app.post('/users', async () => {
   return {
-    statusCode: 201,
-    body: {
-      id: '123',
-      name: body.name,
-      email: body.email,
-      createdAt: new Date().toISOString(),
-    },
+    id: '123',
+    name: 'John Doe',
+    email: '[email protected]',
+    createdAt: new Date().toISOString(),
   };
+}, {
+  validation: { req: { body: createUserSchema } },
 });
 
 // Validate both request and response
-app.get('/users/:id', {
-  middleware: [validation({
-    req: { path: z.object({ id: z.string().uuid() }) },
-    res: { body: userResponseSchema },
-  })],
-}, async (reqCtx) => {
+app.get('/users/:id', async (reqCtx) => {
   const { id } = reqCtx.params;
 
   return {
-    body: {
-      id,
-      name: 'John Doe',
-      email: '[email protected]',
-      createdAt: new Date().toISOString(),
-    },
+    id,
+    name: 'John Doe',
+    email: '[email protected]',
+    createdAt: new Date().toISOString(),
   };
+}, {
+  validation: {
+    req: { path: z.object({ id: z.string().uuid() }) },
+    res: { body: userResponseSchema },
+  },
 });
 
 export const handler = app.resolve.bind(app);

examples/snippets/event-handler/rest/validation_basic.ts

@@ -1,40 +1,23 @@
-import { Router, RequestValidationError } from '@aws-lambda-powertools/event-handler/experimental-rest';
-import { validation } from '@aws-lambda-powertools/event-handler/experimental-rest/middleware';
+import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
 import { z } from 'zod';
 
 const app = new Router();
 
-// Custom error handler for validation errors
-app.onError(RequestValidationError, (error) => {
-  return {
-    statusCode: 422,
-    body: {
-      error: 'Validation Failed',
-      message: error.message,
-      component: error.component,
-      // In development, include detailed validation errors
-      ...(process.env.POWERTOOLS_DEV === 'true' && {
-        details: error.details,
-      }),
-    },
-  };
-});
-
 const userSchema = z.object({
   name: z.string().min(1, 'Name is required'),
   email: z.string().email('Invalid email format'),
   age: z.number().int().positive('Age must be positive'),
 });
 
-app.post('/users', {
-  middleware: [validation({ req: { body: userSchema } })],
-}, async (reqCtx) => {
-  const body = reqCtx.req.body;
-  
+app.post('/users', async () => {
   return {
-    statusCode: 201,
-    body: { id: '123', ...body },
+    id: '123',
+    name: 'John Doe',
+    email: '[email protected]',
+    age: 30,
   };
+}, {
+  validation: { req: { body: userSchema } },
 });
 
 export const handler = app.resolve.bind(app);