Validate JSON responses

Use this when you need Ky to parse a JSON response and verify its shape before your code uses it.

Validate with a Standard Schema

Pass a Standard Schema-compatible validator to .json(). The returned promise resolves to the validator's output type; if validation fails, Ky rejects it with a SchemaValidationError that carries the validator's issues.

1. Install Ky and a compatible validator. Ky's documentation uses Zod 3.24 or later.

   bash
   Copy
   npm install ky zod
   

2. Define the schema and pass it to ky's .json() method. This browser example requests your same-origin /api/user endpoint; with a response matching the schema, it logs the validated user object.

   ts
   Copy
   import ky, {HTTPError, SchemaValidationError, isKyError} from 'ky';
   import {z} from 'zod';
   
   const userSchema = z.object({name: z.string()});
   
   const loadUser = async (): Promise<void> => {
    try {
     const user = await ky('/api/user').json(userSchema);
     console.log(user);
    } catch (error: unknown) {
     if (error instanceof SchemaValidationError) {
      console.error('The response did not match the schema:', error.issues);
     } else if (isKyError(error)) {
      if (error instanceof HTTPError) {
       console.error('The request returned an unsuccessful status:', error.response.status);
      } else {
       console.error('Ky request error:', error.message);
      }
     } else {
      throw error;
     }
    }
   };
   
   void loadUser();
   

The schema check runs after Ky has received and parsed the JSON. A matching response resolves with the validated value. A mismatch enters the first error branch with the validator's issues; an unsuccessful HTTP response enters the Ky error handling instead.

Schema argument

Pitfall: schema errors are not Ky errors

For the error-type distinctions, see How Ky works; this page focuses on reporting the validator's issues when response data fails the schema.

Related

• Send and read JSON
• Ky errors and validation