Exit course
Chapter 6 of 9 Intermediate 8 min read 2 quick checks Updated

Schema Validation with zod and ajv

On this page
  1. zod: one definition, a check and a type
  2. Using the schema in tests
  3. ajv and the API's own schema
  4. What a published schema does not promise
  5. "Contract-ish": where these tests stop

Chapter 2 typed responses with hand-written TypeScript types and warned that those types check nothing at runtime. Schema validation fixes that: you describe the shape once, and every response is checked against it while the test runs. This chapter does it two ways, with zod (a TypeScript-first schema library) and with ajv (a JSON Schema validator) against the schema the API itself publishes, and then looks at what such checks can and cannot tell you.

zod: one definition, a check and a type#

Create lib/schemas.ts:

import { z } from 'zod';

export const ProductSchema = z.object({
  id: z.string().length(26),
  name: z.string().min(1),
  price: z.number().positive(),
  in_stock: z.boolean(),
  co2_rating: z.enum(['A', 'B', 'C', 'D', 'E']),
  category: z.object({ id: z.string(), name: z.string(), slug: z.string() }),
  brand: z.object({ id: z.string(), name: z.string() }),
});

export const ProductPageSchema = z.object({
  current_page: z.number().int(),
  last_page: z.number().int(),
  per_page: z.number().int(),
  total: z.number().int(),
  data: z.array(ProductSchema),
});

export type Product = z.infer<typeof ProductSchema>;

z.infer derives the TypeScript type from the schema, so the type and the runtime check can never drift apart. Replace the hand-written Product in lib/types.ts with a re-export, so existing imports keep working:

export type { Product } from './schemas';

The schema is also more precise than a type can be. Shop ids are 26-character ULIDs, a price must be positive, and the CO2 rating is one of five letters: a TypeScript string or number cannot say any of that.

By default z.object accepts fields you did not list (and leaves them out of the parsed result), which is usually what you want for the same reason as toMatchObject in chapter 2: new fields are backwards compatible. If you need to catch unexpected fields, zod 4 has z.strictObject().

Using the schema in tests#

Create tests/api/schema.spec.ts:

import { test, expect } from '@playwright/test';
import Ajv from 'ajv';
import { ProductPageSchema, ProductSchema } from '../../lib/schemas';

test('every product on page 1 matches the zod schema', async ({ request }) => {
  const response = await request.get('/products', { params: { page: 1 } });
  await expect(response).toBeOK();

  const page = ProductPageSchema.parse(await response.json());
  expect(page.data).toHaveLength(page.per_page);
});

test('a product matches the schema the API publishes', async ({ request }) => {
  const spec = await (await request.get('/docs?api-docs.json')).json();
  const ajv = new Ajv({ strict: false });
  ajv.addSchema(spec, 'toolshop');
  const validate = ajv.getSchema('toolshop#/components/schemas/ProductResponse')!;

  const list = ProductPageSchema.parse(await (await request.get('/products')).json());
  const product = await (await request.get(`/products/${list.data[0].id}`)).json();

  expect(validate(product), ajv.errorsText(validate.errors)).toBe(true);
});

test('zod explains what is wrong', async () => {
  const result = ProductSchema.safeParse({ id: 'x', name: 'Saw', price: '9.99' });
  expect(result.success).toBe(false);
  console.log(result.error?.issues.map((i) => `${i.path.join('.')}: ${i.message}`));
});
[
  'id: Too small: expected string to have exactly 26 characters',
  'price: Invalid input: expected number, received string',
  'in_stock: Invalid input: expected boolean, received undefined',
  'co2_rating: Invalid option: expected one of "A"|"B"|"C"|"D"|"E"',
  'category: Invalid input: expected object, received undefined',
  'brand: Invalid input: expected object, received undefined'
]
  ✓  3 [api] › tests/api/schema.spec.ts:25:1 › zod explains what is wrong (4ms)
  ✓  2 [api] › tests/api/schema.spec.ts:5:1 › every product on page 1 matches the zod schema (167ms)
  ✓  1 [api] › tests/api/schema.spec.ts:13:1 › a product matches the schema the API publishes (538ms)

  3 passed (928ms)

Two ways to call zod:

  • parse() returns the typed data or throws with every issue listed. In a test, throwing is what you want: the test fails with the list in the report, and on success you get a fully typed object to keep asserting on. The first test does exactly that.
  • safeParse() returns { success, data, error } without throwing. Use it when you want to assert that something is invalid, as in the third test, or to collect issues across many items before failing.

Notice what the third test's output does: it lists all problems at once, each with the path to the field. A string price from the server, which a plain toBe comparison might never touch, shows up immediately. That is the main practical value of schema checks: they look at every field on every item, including the ones no assertion mentions.

A list endpoint returns 200 items. Your test checks items[0].price. A bug makes item 137's price a string. Which check catches it?

The status is still 200, the type annotation checks nothing at runtime, and the matcher only looks at the first item. A schema applied to the whole array checks item 137 too and reports its path.

ajv and the API's own schema#

Many APIs publish an OpenAPI document. The Toolshop serves one at /docs?api-docs.json, and its components.schemas section is JSON Schema, which ajv can validate against directly. The second test above:

  1. downloads the OpenAPI document,
  2. registers the whole document with ajv under the name toolshop, so that internal references such as #/components/schemas/BrandResponse resolve,
  3. gets a validator for ProductResponse by JSON pointer,
  4. validates a real product.

strict: false is needed because an OpenAPI document is not a pure JSON Schema. With ajv's default strict mode, getSchema throws strict mode: unknown keyword: "openapi" on the document's top-level fields, and it would do the same for OpenAPI-only keywords such as example. ajv.errorsText(validate.errors) as the assertion message turns a failure into readable text such as data/price must be number.

The appeal is obvious: you do not write the schema, the API team does, and the test checks that the running API matches its own documentation.

What a published schema does not promise#

Try the validator on an empty object:

validate({});          // true
validate({ price: 'x' });            // false: data/price must be number
validate({ brand: { name: 5 } });    // false: data/brand/name must be string

The empty object passes. The published ProductResponse lists properties and their types but marks none of them as required, so it says "if price is present, it is a number", not "a product has a price". This is very common in generated OpenAPI documents, and it means a response with every field missing would validate. The zod schema above, written from the client's point of view, requires every field the client uses, and would fail.

So the two checks answer different questions:

Check Question it answers
ajv against the published schema Does the server behave the way its own documentation says?
zod schema written by the consumer Does the server give this client what it needs?

The second question is the one that breaks your front end. If you can only have one, write the consumer schema.

Every response validates against the API's published OpenAPI schema, yet the front end crashes because price is missing. How is that possible?

Without required, JSON Schema only constrains a property if it is present. strict: false only stops ajv from rejecting unknown keywords; the type checks still run, as the price: 'x' example shows.

"Contract-ish": where these tests stop#

Schema checks in your Playwright suite are a cheap, useful form of contract testing: they fail when a field disappears, changes type or turns null. They are not the whole discipline:

  • They run against one deployed version of the API. A breaking change shows up only after it is deployed to the environment you test against. Consumer-driven contract tools (Pact is the best-known) instead let the consumer publish its expectations so the provider's own build can check them before deploying.
  • They check shape, not meaning. A price that is a positive number but wrong is still a bug only a value assertion catches.

For a team that owns both the front end and the API, consumer schemas in the same suite as the UI tests catch most breaking changes for very little effort. That is a good place to start.

The tests in this chapter used the real API. The next one does the opposite: it takes the API away from the browser and replaces it with responses you control.