The API from the previous lesson has a hole the size of a lorry: if somebody sends {"name": "", "priceEuros": "very expensive", "stock": -5, "colour": "red"}, the coffee is created. eurosToCents("very expensive") produces NaN, the stock ends up negative, the colour field is stored without anyone having planned for it, and from then on GET /v1/coffees returns "priceEuros": null forever. The hand-written checks we left scattered along the way are incomplete, duplicated and each one invents its own message. Today we replace them with declarative schemas using Zod and a single validate(schema, source) middleware that rejects strictly, coerces the types of the query parameters and returns all the failures at once in details, in the exact format we settled on in 02-04. This is the lesson that turns the API into something you can expose to a consumer other than yourself.

1. Why input is never trusted
2. What gets validated: body, path, query and headers
3. Manual validation versus schema validation
4. First steps with Zod: parse and safeParse
5. The types Aroma Store needs
6. z.coerce and the query-parameter problem
7. Strict input with .strict()
8. Composite rules with refine and superRefine
9. Normalisation with transform
10. One schema per operation: partial, extend and merge
11. src/schemas/common.js
12. src/schemas/coffees.js
13. src/schemas/orders.js
14. The validate(schema, source) middleware
15. From ZodError to the contract's error format
16. The routes, with validation
17. Invalid requests and their exact responses
18. Business validation: why it lives in the service
19. Sanitisation, normalisation and the size limit
20. Alternatives to Zod and the link with OpenAPI

The rule is as old as web development and admits no nuance: everything that arrives over the network is hostile until proven otherwise. Not because every consumer is malicious —Aroma Store's SPA is not— but because:

That last point is the decisive one. Client-side validation is usability; server-side validation is correctness. The former exists so the user does not have to wait for the server to say the field is empty; the latter is the only thing that genuinely protects the data, because the API is public and nobody is obliged to go through your SPA to call it.

The consequences of not validating fall into two families:

• Integrity. Corrupt data that propagates: a NaN stored today breaks an invoice three months from now, and by then the origin of the problem is impossible to trace. It also contaminates aggregate calculations: one null price makes the sales report lie.
• Security. SQL injection, NoSQL injection, prototype pollution, denial of service with gigantic bodies or pathological regular expressions. Here we will only see how validation shuts the front door; the complete catalogue of threats and their defences is lesson 04-02.

One principle organises everything else: validate at the edge, trust inside. Once the request has passed the validation middleware, the rest of the code —controller, service, repository— can take for granted that data.priceEuros is a positive number with two decimals. If every layer checks again, the code fills up with useless defensiveness and nobody knows who is responsible for what.

A frequent mistake is validating only the body. There are four inputs and all four are equally manipulable:

In Aroma Store we will validate the first three with schemas. Headers are checked on a case-by-case basis, because their semantics belong to the protocol rather than the domain: the Content-Type of PATCH is already checked in the controller (03-03) and the mandatory Idempotency-Key on POST /v1/orders will be checked in a middleware of its own.

This is how the manual check for POST /v1/coffees ended up in 03-03, and it only covered the required fields:

To cover the full contract we would have to add: that name is a non-empty string of reasonable length, that roast is one of three values, that priceEuros is a positive number with two decimals, that stock is a non-negative integer, that tastingNotes is an array of strings, that there are no unknown fields… and then repeat it for PUT, and for PATCH with everything optional, and again for orders. That would be two hundred lines of if statements to keep in sync with the documentation.

A declarative schema states what must hold, not how to check it. And because it is an object, it can be transformed: from one Zod schema you get a validator, TypeScript types and a JSON Schema for OpenAPI. From an if you get nothing.

Zod has been installed since 03-01. The examples use the stable API, common to versions 3 and 4.

In Aroma Store we will use safeParse, because an invalid body is not an exception: it is the normal case of a client making a mistake, and its response is a well-formed 400, not a program error.

The essential part of the error object: the issues property is an array with all the problems found, not just the first one. Each issue has:

That complete issues array is exactly what the contract needs: validation returns every failure at once (02-04), so the consumer fixes their request in one go rather than in five attempts.

A tour of the constructors we will use, each with its real case:

The case of priceEuros is worth stopping at. The contract of 02-05 says "euros with two decimals on the outside, cents on the inside". Zod has no "decimal with two places" type, so it is composed:

A more readable and more robust way of expressing the same thing, avoiding floating-point noise, is to check the textual representation:

This way 14.5 and 14.50 both pass (they are the same number), and 14.567 is rejected with a 400. Accepting three decimals would mean accepting fractions of a cent that would be lost in the conversion, and with them the accounting balance.

As we saw in 03-03, everything arriving in the URL is text. ?limit=20&available=true produces { limit: '20', available: 'true' }. A z.number() applied to '20' fails, and rightly so.

z.coerce converts before validating:

Careful with z.coerce.boolean(): it applies JavaScript's conversion, where any non-empty string is truthy. So ?available=false would become true, which is exactly the bug we fixed in exercise 1 of 03-03. For booleans in the URL you have to be explicit:

This is the kind of detail that separates an API that seems to work from one that works.

By default, z.object() silently discards keys that are not in the schema. The contract of 02-05 decided the opposite: strict input, unknown field → 400.

The three reasons behind the decision, worth having to hand because the debate always resurfaces:

1. It catches client typos. Someone sending priceEuro (without the s) gets a cheerful 201 and a coffee with a default price under the lax version. Under the strict one, they get a 400 telling them exactly which field does not exist.
2. It prevents mass assignment. If tomorrow the internal model had a featured or customerRole field, a body including it could end up being stored if the code does {...data}. Strict input shuts that door at the edge.
3. It makes evolution explicit. Adding a field to the API becomes a conscious decision reflected both in the schema and in openapi.yaml.

The honest trade-off: strict input reduces tolerance. A client that echoes back a representation we returned —_links and createdAt included— will get a 400. It is a real and frequent case with PUT. It is solved by documenting it clearly and, if necessary, explicitly ignoring the read-only fields in the schema instead of rejecting them.

Some rules belong not to one field but to the relationship between several. refine adds an arbitrary check:

The path matters: without it, the failure is not associated with any field and the error's details ends up with no field.

superRefine lets you emit several problems and choose their code:

Where the boundary lies. The schema holds the rules that can be checked by looking only at the request: formats, ranges, coherence between fields. Anything that needs to consult the state of the system —does that coffee exist? is there stock? has this order already been paid?— does not belong here. We will come back to this in section 18, because it is the most common confusion of this lesson.

transform changes the value after validating it. It serves us in two ways:

The second temptation is strong and must be resisted in part. If the schema returned priceCents, the controller would receive an object that no longer looks like the public contract, and the unit translation would be split between the schema and the mapper. In Aroma Store we keep the conversion in the service (eurosToCents, 03-03) and use transform only for normalising: trimming whitespace, unifying the capitalisation of the origin, removing duplicate tasting notes. A useful rule: transform cleans up what the client typed; it does not translate between the public world and the internal one.

POST, PUT and PATCH do not ask for the same thing, so they do not share a schema; they share pieces.

And the composition tools:

One ordering detail that costs an afternoon if you find it out the hard way: .strict() is applied last. base.strict().partial() works, but if you chain extend after strict, it is worth closing it again. That is why in our files .strict() is always the final call.

We start with the shared pieces, so as not to repeat them in every resource:

The default() calls matter: thanks to them the controller always receives limit and offset as numbers, and the req.query.limit === undefined ? 20 : ... lines from 03-03 disappear.

The .strict() on the query schema is what fulfils the promise of 02-06 that an unknown parameter produces a 400. ?pageSize=20 (the most frequent slip, because half the APIs out there call it that) stops being a silently ignored filter and becomes an explicit error the integrator sees on their very first test.

The most important note in this file is the one on createOrderSchema: the client does not send prices. It is a perfect case of why validation is also design. Accepting priceEuros inside an order item would be a textbook business vulnerability; rejecting it with strict input eliminates it at the root.

A single piece for all three inputs:

Three design decisions worth justifying:

Why req[source] is replaced. After the middleware, req.query.limit is the number 20, not the string '20', and req.body.tastingNotes is [] even if the client never sent it. The controller is left with no conversions and no defaults: all of that happened at the edge. It is the materialisation of "validate at the edge, trust inside".

Why Zod's codes are translated. too_small or unrecognized_keys are implementation details of a library. If we exposed them, upgrading Zod could change our API's contract, and that is unacceptable (02-07). The translation insulates us: switching library would not change a single visible code.

Why the messages are not filtered. Zod's messages are readable and in most cases we have written them ourselves inside the schema. The ones we have not —Zod's own defaults— can be replaced wholesale with a global map; exercise 3 covers it.

A note about Express 5. In Express 4, req.query is an ordinary property and can be reassigned. In Express 5 it became a read-only getter, so the assignment fails silently. The portable solution is to store the result in a property of your own (req.validated = { ...req.validated, [source]: result.data }) and read from there in the controller. Since this course uses Express 4, we keep the direct form, which is more readable.

With the above in place, a request with four failures produces this response:

Four failures, one single response. That is the promise of 02-04, and it is what separates a pleasant API from an unbearable one: with "fail on the first error" validation, the integrator would need four attempts and four deployments of their client to discover the same thing.

For nested fields, path.join('.') produces readable paths:

Now the routes also declare the input contract. src/routes/coffees.js ends up like this:

It reads like a specification: for each method and URI, what is validated and who handles it. And the controller slims down remarkably, because every manual check disappears:

create has gone from twenty lines to three. That is the measurable benefit of moving validation to the edge.

This last case has more to it than meets the eye. A malformed id now produces 400 invalid_parameter and never reaches the repository. The alternative —letting it through and returning 404 coffee_not_found— would also be defensible, but we chose the 400 because it distinguishes "you mistyped the identifier" from "that coffee does not exist", and it also saves a database query for every junk request. With SQL behind it (03-05), that upfront validation is one more layer against injection too.

There are rules a schema cannot check, and confusing them with format validation is the most common conceptual mistake of this lesson:

The three underlying reasons:

1. The schema has no access to the data. Putting a query inside a refine would make the schema asynchronous, database-dependent and impossible to reuse for generating documentation.
2. State changes. Between validating "there is stock" and deducting it, another order can slip in. The check must happen inside the same transaction as the deduction (03-05); doing it at the edge gives a false sense of safety.
3. The error code is different. An invalid format is 400 invalid_data; insufficient stock is 409 insufficient_stock, a state conflict rather than a writing mistake. They are different families in the catalogue of 02-04.

This is how that validation looks in the order service, written today in the provisional form that 03-07 will turn into throw new ApiError(...):

Notice that here too every problem is accumulated before responding. The consistency with schema validation is deliberate: if an order has three items out of stock, the client deserves to hear about all three at once.

Three concepts that get mixed up and that do different things:

Aroma Store validates and normalises in the schema. Sanitisation is a matter of output context and is not done here: trying to "clean" HTML on the way in produces mutilated data —a customer whose surname is O'Brien should not lose the apostrophe— and a false sense of security. The right thing is to store the text as it is and escape it at the moment of use: prepared statements for SQL (03-05), HTML escaping in the client that renders it. In 04-02 the reasoning is developed in detail.

As for the size limit, we already set it in 03-02:

It is a defence that schema validation cannot give you, because it acts earlier: without a limit, a 500 MB body is parsed entirely into memory and the process dies before Zod sees anything. With limit, Express responds 413. That 413 produces an ugly Express response today; in 03-07 we will turn it into the catalogue's body_too_large.

One final point: validation protects against prototype pollution. A body containing {"__proto__": {"isAdmin": true}} could, combined with a careless Object.assign, modify the prototype of every object in the process. With .strict(), that key is simply an unknown field and the request dies at the edge with a 400.

That last row points at an important topic. In 02-08 we wrote openapi.yaml as the contract's source of truth, and in this module we have written Zod schemas that say practically the same thing. We have two definitions of the same truth, and two definitions end up diverging: somebody adds a field to the Zod schema and forgets the YAML.

The three ways of resolving it:

1. Generate OpenAPI from Zod, with tools such as zod-to-json-schema or @asteasolutions/zod-to-openapi. The code rules.
2. Generate the validators from OpenAPI, with AJV and the contract's JSON Schema. The specification rules; it is the most coherent option with API-first.
3. Keep both and verify in CI that the implementation complies with the specification, using contract tests.

The third is the most practical and the one we will see in 05-04, where we will automatically check that every response validates against the published schema. For now it is enough to be aware of the risk: every time you touch a schema in src/schemas/, touch openapi.yaml too. It is exactly the drift we warned about in 02-08.

1. Validating only the body. Query and path parameters are just as manipulable, and ?limit=999999 is an availability problem.

2. Using z.coerce.boolean() for a URL parameter. It turns any non-empty string into true, including 'false'. Use z.enum(['true','false']).transform(...).

3. Putting database queries inside a refine. The schema must not know about the state of the system. That check belongs to the service and often to the same transaction as the write.

4. Returning Zod's internal codes to the client. too_small is a detail of a dependency; if you publish it, upgrading the library forces you to change the contract.

5. Forgetting .strict(). Without it, the object is validated but unknown fields are silently discarded and the strict-input contract stops being honoured.

6. Reusing the POST schema for PATCH. PATCH requires everything to be optional; using the POST one forces the client to resend the whole resource, which is what PUT does.

7. Trusting that the client already validates. Never. The SPA validates for usability; the server validates for correctness.

8. Validating after touching the database. The order in the middleware chain matters: validate goes before the controller, always.

Tip: when you are unsure whether a check belongs to the schema or to the business, ask yourself whether you could answer by looking only at the text of the request. If you need to look something up, it is business and it belongs in the service.

Write the schema createReviewSchema for POST /v1/coffees/:id/reviews. According to the contract: rating is a required integer from 1 to 5, comment is optional text of between 10 and 2000 characters, and no other field is accepted (in particular status, which the server sets to pending_moderation). Add the rule that if there is a comment, it cannot be nothing but whitespace. Show the route with its validation.

An integrator complains that POST /v1/orders with this body returns 400 and does not understand why:

List every failure createOrderSchema will detect, write the complete response the API returns, and explain to the integrator why rejecting priceEuros and totalEuros is not an annoyance but a protection.

Zod's default messages are written in the library's own voice ("Expected number, received string"), which clashes with the wording style of the rest of our messages and cannot be adapted for consumers who ask for another language with Accept-Language. Propose a solution that replaces those default messages without having to write a message by hand in every field of every schema, and implement it alongside translateCode/toDetails. Comment on the advantage of having a stable code as well as a message.

Solution 1

The .trim() before .min(10) solves the whitespace-only comment rule all by itself: " " becomes the empty string and fails the minimum. It is more elegant than a refine, and it shows that the order of the chained calls in Zod carries meaning.

About status: it does not appear in the schema on purpose. With .strict(), a client sending "status": "published" gets 400 unknown_field and cannot bypass moderation. It is the same pattern as priceEuros in order items: fields the server sets are not accepted on input, they are rejected.

Solution 2

Failures detected, three in total:

1. items.0.priceEuros — unknown field inside the item: orderItemSchema is .strict() and only accepts coffeeId and quantity.
2. totalEuros — unknown field at the root: createOrderSchema is .strict() and only accepts customerId and items.
3. items.1.coffeeId — cof_001 appears twice, caught by the superRefine.

The API's response:

Explanation for the integrator: the prices and the total are calculated by the server from the catalogue at the moment the order is created, and that is why the API does not accept them as input. If it did, anyone could send priceEuros: 0.01 and buy speciality coffee for a penny; on top of that, a totalEuros sent by the client might not match the sum of the items, and then someone would have to decide which of the two numbers is the right one. Rejecting them removes a fraud and an ambiguity in one stroke. The 201 response does return priceEuros per item and totalEuros, already calculated and frozen, which is what the client needs in order to display them.

About the repeated coffee: the contract prefers a single item per coffee with the quantities grouped, because two items for the same product make the stock deduction ambiguous and complicate partial returns.

Solution 3

Zod allows a global error map that applies to every schema, without touching a single field:

It is installed once, in src/app.js, before mounting the routes:

Now the failure from the earlier example returns "Expected number but received string", written in our voice and ready to be swapped for a translated map when the API starts honouring Accept-Language on its messages, without a single field of any schema having been touched.

The advantage of having code as well as message: the message is for humans —it can change, be translated or be rewritten so that it reads better, and none of that breaks anyone. The code is for machines: a client can write if (detail.code === 'required') and trust that it will not change, because it is part of the contract and subject to the versioning rules of 02-07. Separating the two lets you improve the wording of the messages on any given Tuesday without publishing a new version of the API. It is the same principle by which enums are in snake_case and never translated (02-05).

The API no longer accepts rubbish. The schemas in src/schemas/ are now the executable definition of what comes in: types, ranges, identifier formats, enums, ISO-8601 dates, prices with two decimals and lists with a maximum length; with .strict() to honour the strict input of 02-05, z.coerce to convert the query parameters that always arrive as text, default() so that the controller receives the contract's values already applied, and partial() so that PATCH demands exactly what it should. A single middleware, validate(schema, source), applies all of that to body, query and params, replaces the input with the parsed value and translates the ZodError into the contract's format: 400 invalid_data for the body, 400 invalid_parameter for the parameters, and every failure at once in details, each with its field, its stable code and its message.

Just as important is what we have not put into the schemas. Whether a coffee exists, the available stock, an order that is already paid or the permission to see a resource all depend on the state of the system, change between two requests and carry error codes from another family (409, not 400). That validation lives in the service, and some of its checks will have to happen inside the same transaction as the write.

And that is exactly where we are heading. Everything built so far rests on two in-memory arrays that empty out with each restart of node --watch, that cannot handle serious queries and that cannot guarantee that deducting stock across three items is an atomic operation. In 03-05, Persistence and the Data Access Layer, we will replace that store with SQLite via better-sqlite3 behind the repository pattern: a SQL schema with an integer price_cents, versioned migrations and seed data, prepared statements that shut the door on injection, safe dynamic queries for the filters of 02-06, transactions for creating an order while deducting stock, optimistic concurrency control with version_conflict and genuine cursor pagination. And we will do it without touching a single line of the controllers or the services, which is the promise we made in 03-01 when we separated the layers.