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/http.md

@@ -169,11 +169,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/http/validation_basic.ts

@@ -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: 'john@example.com',
+    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: 'john@example.com',
-      createdAt: new Date().toISOString(),
-    },
+    id,
+    name: 'John Doe',
+    email: 'john@example.com',
+    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/http/validation_error_handling.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: 'john@example.com',
+    age: 30,
   };
+}, {
+  validation: { req: { body: userSchema } },
 });
 
 export const handler = app.resolve.bind(app);

examples/snippets/event-handler/http/validation_query_headers.ts

@@ -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();
@@ -11,22 +10,16 @@ const listUsersQuerySchema = z.object({
   sort: z.enum(['name', 'email', 'createdAt']).optional(),
 });
 
-app.get('/users', {
-  middleware: [validation({ req: { query: listUsersQuerySchema } })],
-}, async (reqCtx) => {
-  const url = new URL(reqCtx.req.url);
-  const query = Object.fromEntries(url.searchParams.entries());
-  // query is typed with validated schema
-  
+app.get('/users', async () => {
   return {
-    body: {
-      users: [],
-      pagination: {
-        page: query.page || 1,
-        limit: query.limit || 10,
-      },
+    users: [],
+    pagination: {
+      page: 1,
+      limit: 10,
     },
   };
+}, {
+  validation: { req: { query: listUsersQuerySchema } },
 });
 
 // Validate headers
@@ -35,15 +28,23 @@ const apiKeyHeaderSchema = z.object({
   'content-type': z.string().optional(),
 });
 
-app.post('/protected', {
-  middleware: [validation({ req: { headers: apiKeyHeaderSchema } })],
-}, async () => {
-  return { statusCode: 200, body: 'Access granted' };
+app.post('/protected', async () => {
+  return { message: 'Access granted' };
+}, {
+  validation: { req: { headers: apiKeyHeaderSchema } },
 });
 
 // Validate multiple components
-app.post('/users/:id/posts', {
-  middleware: [validation({
+app.post('/users/:id/posts', async (reqCtx) => {
+  const { id } = reqCtx.params;
+  
+  return {
+    postId: '456',
+    userId: id,
+    title: 'New Post',
+  };
+}, {
+  validation: {
     req: {
       path: z.object({ id: z.string().uuid() }),
       body: z.object({
@@ -54,19 +55,7 @@ app.post('/users/:id/posts', {
         'content-type': z.literal('application/json'),
       }),
     },
-  })],
-}, async (reqCtx) => {
-  const { id } = reqCtx.params;
-  const body = reqCtx.req.body;
-  
-  return {
-    statusCode: 201,
-    body: {
-      postId: '456',
-      userId: id,
-      title: body.title,
-    },
-  };
+  },
 });
 
 export const handler = app.resolve.bind(app);