Guides & concepts
Validation
Three schemas, two protocols, one invariant.
| Schema | Validates | Runs |
|---|---|---|
| pathParamsSchema | Bound path parameters | Before the URL is built |
| requestSchema | The request body or query params | Before the request is sent |
| responseSchema | The response body | After the response arrives |
Two protocols, checked in order
hapi accepts anything with safeParse and anything implementing Standard Schema V1. safeParse is tested first, because Zod satisfies both and that path is always synchronous.
Issues are not normalised
failure.issues is typed unknown on purpose. A ZodError and a Standard Schema issue array both reach you intact — flattening them would lose information only the originating library can interpret.
Deferring response validation
For a large response where parsing would block a render, declare the schema as async. The data resolves immediately and validation runs in a detached promise, reporting failures through onResponseValidationError without throwing.
responseSchema: { schema: bigSchema, mode: 'async' }