Skip to the content

/

Zod and OpenAPI

Zod 4

Zod and OpenAPI: 0% done

Module 1 · Data on the move

Programs pass data to each other

Loading the slide…

A line of words about as long as a slide’s first line, and its second.

Another line, shorter.

1 / 194 · Data on the move

Course progress

0%

Programs pass data to each other
, 1 to practiseJSON is how most data travels
Data arrives from forms, addresses and APIs
, 1 to practiseData from outside can be anything
Validation means checking before you use
, 1 to practiseTypeScript's types vanish when the program runs
, 1 to practiseChecking by hand gets long fast
, 1 to practiseZod describes data once and checks it for you
Recap

What you need: Node.js, a terminal and a project
Installing Zod
A schema is a description of valid data
, 1 to practiseparse gives back the data, or throws
Reading your first error
, 1 to practisesafeParse returns a result instead of throwing
, 1 to practiseTry it: a safe parse
, 1 to practiseWhen to use parse and when safeParse
, 1 to practiseA first look at objects
Try it yourself
Recap

Each basic kind of value has a schema
, 1 to practiseZod checks types, it doesn't convert them
Checks narrow what a string may be
, 1 to practiseNumbers: whole numbers, ranges and steps
Formats: emails, links, ids and dates
, 1 to practiseDates travel as ISO 8601 text
, 1 to practiseSome methods tidy the text first
, 1 to practiseYour own message for each check
, 1 to practiseTry it: a username
Recap

z.object describes each field
, 1 to practiseUnknown keys are dropped
, 1 to practiseObjects inside objects
, 1 to practiseArrays: lists of one kind of thing
Tuples: a fixed list with a type per position
, 1 to practiseRecords: objects used as dictionaries
, 1 to practiseReusing a field through .shape
, 1 to practisePutting it together
, 1 to practiseTry it: a book in a library
Recap

, 1 to practiseMissing, undefined, null and empty are different
, 1 to practiseoptional: the field may be left out
nullable: the field is there, but empty on purpose
, 1 to practisedefault fills in a missing value
default skips the checks; prefault runs them
catch replaces a bad value with a fallback
, 1 to practiseBlank form fields send empty strings
, 1 to practiseChoosing the right one
, 1 to practiseTry it: a profile with gaps
Recap

, 1 to practiseA literal allows exactly one value
An enum is a fixed list of allowed strings
, 1 to practiseReading an enum's values
, 1 to practiseEnums from TypeScript enums and constant objects
Enums describe states
, 1 to practisePatterns of text with templateLiteral
, 1 to practiseCommon mistakes with choices
Recap

A union accepts one of several shapes
, 1 to practiseZod tries each option in order
When nothing matches, you get every option's errors
A discriminated union picks the option by one field
, 1 to practiseTypeScript narrows on the discriminator
, 1 to practiseTry it: ways to pay
, 1 to practiseClearer errors, and faster
, 1 to practiseModel states, not flags
, 1 to practiseUnions inside objects and arrays
Recap

A short recap of TypeScript types
, 1 to practisez.infer turns a schema into a type
One source of truth
, 1 to practiseparse turns unknown into a typed value
, 1 to practiseInput and output can differ
, 1 to practiseTry it: the type going in and the type coming out
, 1 to practiseBrands tell apart strings that look alike
readonly freezes what you parsed
, 1 to practiseSchemas make types, not the other way around
Recap

A ZodError is a list of issues
, 1 to practiseZod reports every problem at once
The error parameter sets the message
, 1 to practiseA function can choose the message
treeifyError nests messages like your data
, 1 to practiseflattenError for simple forms
, 1 to practiseTry it: errors for a form
prettifyError for logs and terminals
, 1 to practiseMessages for the whole app, and in other languages
Recap

Build big schemas from small ones
, 1 to practiseextend adds fields
, 1 to practisepick and omit keep or drop fields
, 1 to practisepartial makes every field optional
, 1 to practiseTry it: one book, three schemas
Combining two objects with spread
A schema that contains itself
, 1 to practiseTwo schemas that point at each other
, 1 to practiseFunctions that build schemas
Recap

Some rules aren't about shape
, 1 to practise.refine adds a rule of your own
, 1 to practiseRules about the whole object, pointed at one field
, 1 to practiseTry it: passwords that match
, 1 to practiseWhen refinements run
superRefine reports several issues
, 1 to practiseabort stops at the first failed rule
, 1 to practiseChecks that take time need parseAsync
, 1 to practiseWhich rules belong in a schema
Recap

transform changes the value after it passes
, 1 to practisepipe checks the result with another schema
preprocess runs before the schema
, 1 to practisez.coerce converts with JavaScript's own rules
z.stringbool reads yes and no written as text
, 1 to practiseQuery strings: everything arrives as text
, 1 to practiseTry it: a search page
, 1 to practiseForm data from a browser
Settings from environment variables
Recap

Validate at the edges
Checking a request body on a server
, 1 to practiseA useful error reply
, 1 to practiseTry it: a request handler
With a framework: Hono and zValidator
, 1 to practiseChecking what an API sends back
, 1 to practiseHow strict to be with responses
, 1 to practiseValidation is part of security
, 1 to practiseOne schema for both sides
Recap

An API needs a description
, 1 to practiseHTTP in one slide: methods, paths and statuses
OpenAPI is a standard way to describe an API
The parts of an OpenAPI document
, 1 to practiseAn operation: parameters, body and responses
, 1 to practiseSchemas in OpenAPI are JSON Schema
, 1 to practisecomponents and $ref avoid repeating yourself
, 1 to practiseWrite it by hand, or generate it from code
Recap

Installing Hono and @hono/zod-openapi
createRoute describes one operation
, 1 to practiseapp.openapi connects the route to a handler
, 1 to practiseEvery part of a request has a validator
, 1 to practiseQuery parameters need coercion
, 1 to practiseRequest bodies: JSON or forms
, 1 to practiseResponses are type-checked, not validated
, 1 to practiseA defaultHook shapes every validation error
Recap

Serving the document
, 1 to practiseName schemas with .openapi()
Documenting parameters
, 1 to practiseSummaries, descriptions, tags and ids
Describing who may call
, 1 to practiseWriting openapi.json to a file
A documentation site from the document
, 1 to practiseWhat the document can't say
Recap

A client that knows the API
Generating types with openapi-typescript
, 1 to practiseReading the generated types
openapi-fetch: a small typed fetch
, 1 to practiseCalling endpoints
, 1 to practisedata, error and response
Middleware for every call
, 1 to practiseGenerated types are promises, not checks
, 1 to practiseOther ways to get a typed client
Recap

Data travels in two directions
z.codec pairs decode with encode
, 1 to practisedecode, encode and parse
, 1 to practiseTry it: a price in cents
, 1 to practiseCodecs for wire formats
z.toJSONSchema turns a schema into JSON Schema
, 1 to practiseInput or output: which side to describe
What JSON Schema can't hold
, 1 to practise.meta() attaches documentation
Recap

, 1 to practiseBuild schemas once, parse many times
, 1 to practiseWhat makes parsing faster or slower
, 1 to practiseChanging a contract without breaking clients
Be strict in what you accept, tolerant in what you read
, 1 to practiseWhen you must break: deprecate, then version
Testing schemas with examples
, 1 to practiseTesting the contract
, 1 to practiseReviewing a schema
Recap

The challenge
, 1 to practiseA sign-up form end to end
, 1 to practiseWrite it: an order with delivery
, 1 to practiseWhich type goes where
, 1 to practiseReviewing a route
, 1 to practiseA leak no type caught
, 1 to practiseA client that handles everything
, 1 to practiseEvolving the order schema
, 1 to practiseRound trips
What you can do now