feat(event-handler): add validation support for REST router (#4736)

Co-authored-by: svozza <svozza@amazon.com>

Author: sdangol

.gitignore

@@ -52,4 +52,5 @@ tsconfig.tsbuildinfo
 .claude
 .amazonq
 .kiro
-.github/instructions
+.github/instructions
+aidlc-docs

docs/features/event-handler/http.md

@@ -9,7 +9,7 @@ Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Bala
 ## Key Features
 
 * Lightweight routing to reduce boilerplate for API Gateway REST/HTTP API, ALB and Lambda Function URLs.
-* 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
@@ -92,6 +92,26 @@ For your convenience, when you return a JavaScript object from your route handle
 !!! tip "Automatic response format transformation"
     The event handler automatically ensures the correct response format is returned based on the event type received. For example, if your handler returns an API Gateway v1 proxy response but processes an ALB event, we'll automatically transform it into an ALB-compatible response. This allows you to swap integrations with little to no code changes.
 
+If you need to control the status code or headers alongside auto-serialization, return an object with `statusCode` and `headers` fields. The `body` field accepts any JSON-serializable value — object or array — and is automatically serialized. Omitting `body` produces an empty response body, which is useful for responses like `204 No Content`.
+
+=== "index.ts"
+
+    ```ts hl_lines="7-9 14 18"
+    --8<-- "examples/snippets/event-handler/http/gettingStarted_extended_proxy_result.ts"
+    ```
+
+    1. Set a custom status code alongside JSON auto-serialization
+    2. Set custom response headers
+    3. Object body is automatically serialized to JSON
+    4. Array body is automatically serialized to JSON
+    5. Omitting `body` produces an empty response body
+
+=== "Response"
+
+    ```json hl_lines="2"
+    --8<-- "examples/snippets/event-handler/http/samples/gettingStarted_extended_proxy_result.json"
+    ```
+
 ### Dynamic routes
 
 You can use `/todos/:todoId` to configure dynamic URL paths, where `:todoId` will be resolved at runtime.
@@ -182,11 +202,111 @@ If you prefer to use the decorator syntax, you can use the same methods on a cla
 
 ### Data validation
 
-!!! note "Coming soon"
+Event Handler supports built-in request and response validation using [Standard Schema](https://standardschema.dev){target="_blank"}, a common specification supported by popular TypeScript validation libraries including [Zod](https://zod.dev){target="_blank"}, [Valibot](https://valibot.dev){target="_blank"}, and [ArkType](https://arktype.io){target="_blank"}.
+
+!!! note "Body validation is limited to JSON-serializable values"
+    Standard Schema validators operate on JavaScript values, not raw bytes. For body validation, Event Handler deserializes the body before passing it to your schema: `application/json` content is parsed as an object, all other content types are passed as a plain string. Binary data, streams, and other non-serializable response types cannot be validated.
+
+#### Validating requests
+
+Pass a `validation` option to your route handler with a `req` configuration to validate the incoming request. Validation runs before your handler, and if it fails, Event Handler automatically returns a **422 Unprocessable Entity** response with structured error details.
+
+Validated data is available via `reqCtx.valid.req` and is fully typed based on your schema. Only the fields you provide schemas for are accessible: accessing an unvalidated field (e.g., `reqCtx.valid.req.headers` when no headers schema was configured) is a compile-time error.
+
+=== "index.ts"
+
+    ```ts hl_lines="3 7-10 15 19"
+    --8<-- "examples/snippets/event-handler/http/gettingStarted_validation_request.ts"
+    ```
+
+    1. Access the validated and typed request body via `reqCtx.valid.req.body`
+
+=== "Request"
+
+    ```json
+    --8<-- "examples/snippets/event-handler/http/samples/gettingStarted_validation_req.json"
+    ```
+
+=== "Response"
+
+    ```json
+    --8<-- "examples/snippets/event-handler/http/samples/gettingStarted_validation_res.json"
+    ```
+
+=== "Validation error (422)"
+
+    ```json
+    --8<-- "examples/snippets/event-handler/http/samples/gettingStarted_validation_422.json"
+    ```
+
+You can validate any combination of `body`, `headers`, `path` parameters, and `query` parameters — at least one must be specified:
+
+=== "index.ts"
+
+    ```ts hl_lines="8-11 17-19"
+    --8<-- "examples/snippets/event-handler/http/gettingStarted_validation_request_parts.ts"
+    ```
+
+    1. Query params are always strings — `z.coerce.number()` coerces and validates the value, typing it as `number`
+    2. Validated path parameters available via `reqCtx.valid.req.path`
+    3. `page` and `limit` are typed as `number` — no manual casting needed
+    4. Validated headers available via `reqCtx.valid.req.headers`
+    5. Headers are always strings — `z.coerce.number()` coerces and validates the value, typing it as `number`
+
+#### Validating responses
+
+Pass a `validation` option to your route handler with a `res` configuration to validate the outgoing response body and headers after your handler executes. If validation fails, Event Handler returns a **500 Internal Server Error**.
+
+Response validation is useful for ensuring your handler returns the expected shape and catching contract violations early.
+Validated data is available via `reqCtx.valid.res` and is fully typed based on your schema. Only the fields you provide schemas
+for are accessible: accessing an unvalidated field (e.g., `reqCtx.valid.res.headers` when no headers schema was configured) is a compile-time error.
+
+=== "index.ts"
+
+    ```ts hl_lines="3 7-11 19"
+    --8<-- "examples/snippets/event-handler/http/gettingStarted_validation_response.ts"
+    ```
+
+    1. If the response doesn't match the schema, a 500 is returned
+
+=== "Validation error (500)"
+
+    ```json
+    --8<-- "examples/snippets/event-handler/http/samples/gettingStarted_validation_500.json"
+    ```
+
+You can also validate response headers by providing a `headers` schema in the `res` configuration. This is useful for enforcing that required headers — such as correlation IDs or cache directives — are always present:
+
+=== "index.ts"
+
+    ```ts hl_lines="7-10 26"
+    --8<-- "examples/snippets/event-handler/http/gettingStarted_validation_response_headers.ts"
+    ```
+
+    1. Enforce that the correlation ID is a valid UUID
+    2. If either required header is absent or invalid, a 500 is returned
+    3. Headers are always strings — `z.coerce.number()` coerces and validates the value, typing it as `number`
+
+You can combine both request and response validation in a single route by providing both `req` and `res`:
 
-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.
+=== "index.ts"
+
+    ```ts hl_lines="7-13 18 23-24"
+    --8<-- "examples/snippets/event-handler/http/gettingStarted_validation_combined.ts"
+    ```
+
+    1. Access the validated and typed request body via `reqCtx.valid.req.body`
+    2. If the response doesn't match the schema, a 500 is returned
+
+!!! tip
+    If you need request validation but want to skip runtime response validation, annotate your handler's return type directly and TypeScript will enforce the return shape at compile time:
+
+    ```ts hl_lines="9 13 19"
+    --8<-- "examples/snippets/event-handler/http/gettingStarted_validation_response_types.ts"
+    ```
 
-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.
+    1. TypeScript enforces `Todo` as the return type at compile time
+    2. Only request validation runs at runtime — no response validation
 
 ### Accessing request details
 

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

@@ -0,0 +1,25 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { Context } from 'aws-lambda';
+
+const app = new Router();
+
+app.post('/todos', () => ({
+  statusCode: 201, // (1)!
+  headers: { 'x-todo-id': '123' }, // (2)!
+  body: { id: '123', title: 'Buy milk' }, // (3)!
+}));
+
+app.get('/todos', () => ({
+  statusCode: 200,
+  body: [
+    { id: '1', title: 'Buy milk' },
+    { id: '2', title: 'Take out trash' },
+  ], // (4)!
+}));
+
+app.delete('/todos/:id', () => ({
+  statusCode: 204, // (5)!
+}));
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

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

@@ -0,0 +1,30 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { Context } from 'aws-lambda';
+import { z } from 'zod';
+
+const app = new Router();
+
+const createTodoSchema = z.object({ title: z.string() });
+
+const todoResponseSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  completed: z.boolean(),
+});
+
+app.post(
+  '/todos',
+  (reqCtx) => {
+    const { title } = reqCtx.valid.req.body; // (1)!
+    return { id: '123', title, completed: false };
+  },
+  {
+    validation: {
+      req: { body: createTodoSchema },
+      res: { body: todoResponseSchema }, // (2)!
+    },
+  }
+);
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

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

@@ -0,0 +1,24 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { Context } from 'aws-lambda';
+import { z } from 'zod';
+
+const app = new Router();
+
+const createTodoSchema = z.object({
+  title: z.string(),
+  completed: z.boolean().optional().default(false),
+});
+
+app.post(
+  '/todos',
+  (reqCtx) => {
+    const { title, completed } = reqCtx.valid.req.body; // (1)!
+    return { id: '123', title, completed };
+  },
+  {
+    validation: { req: { body: createTodoSchema } },
+  }
+);
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

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

@@ -0,0 +1,37 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { Context } from 'aws-lambda';
+import { z } from 'zod';
+
+const app = new Router();
+
+const pathSchema = z.object({ todoId: z.string().uuid() });
+const querySchema = z.object({
+  page: z.coerce.number().int().positive(), // (1)!
+  limit: z.coerce.number().int().positive().max(100),
+});
+const headerSchema = z.object({
+  'x-api-key': z.string(),
+  'x-max-age': z.coerce.number().int().nonnegative(), // (5)!
+});
+
+app.get(
+  '/todos/:todoId',
+  (reqCtx) => {
+    const { todoId } = reqCtx.valid.req.path; // (2)!
+    const { page, limit } = reqCtx.valid.req.query; // (3)!
+    const { 'x-api-key': apiKey } = reqCtx.valid.req.headers; // (4)!
+    return { id: todoId, page, limit, apiKey };
+  },
+  {
+    validation: {
+      req: {
+        path: pathSchema,
+        query: querySchema,
+        headers: headerSchema,
+      },
+    },
+  }
+);
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

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

@@ -0,0 +1,24 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { Context } from 'aws-lambda';
+import { z } from 'zod';
+
+const app = new Router();
+
+const todoSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  completed: z.boolean(),
+});
+
+app.get(
+  '/todos/:id',
+  ({ params }) => {
+    return { id: params.id, title: 'Buy milk', completed: false };
+  },
+  {
+    validation: { res: { body: todoSchema } }, // (1)!
+  }
+);
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

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

@@ -0,0 +1,31 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { Context } from 'aws-lambda';
+import { z } from 'zod';
+
+const app = new Router();
+
+const responseHeaderSchema = z.object({
+  'x-correlation-id': z.string().uuid(), // (1)!
+  'x-max-age': z.coerce.number().int().nonnegative(), // (3)!
+});
+
+app.get(
+  '/todos/:id',
+  ({ params }) => {
+    return {
+      statusCode: 200,
+      headers: {
+        'content-type': 'application/json',
+        'x-correlation-id': crypto.randomUUID(),
+        'x-max-age': 300,
+      },
+      body: { id: params.id, title: 'Buy milk' },
+    };
+  },
+  {
+    validation: { res: { headers: responseHeaderSchema } }, // (2)!
+  }
+);
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

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

@@ -0,0 +1,24 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { Context } from 'aws-lambda';
+import { z } from 'zod';
+
+const app = new Router();
+
+const createTodoSchema = z.object({ title: z.string() });
+
+type Todo = { id: string; title: string; completed: boolean };
+
+app.post(
+  '/todos',
+  (reqCtx): Todo => {
+    // (1)!
+    const { title } = reqCtx.valid.req.body;
+    return { id: '123', title, completed: false };
+  },
+  {
+    validation: { req: { body: createTodoSchema } }, // (2)!
+  }
+);
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

examples/snippets/event-handler/http/samples/gettingStarted_extended_proxy_result.json

@@ -0,0 +1,9 @@
+{
+  "statusCode": 201,
+  "headers": {
+    "Content-Type": "application/json",
+    "x-todo-id": "123"
+  },
+  "body": "{\"id\":\"123\",\"title\":\"Buy milk\"}",
+  "isBase64Encoded": false
+}