as User is deleted by the compiler and checks nothing at runtime, and both JSON.parse and Response.json() are typed as any, so a network payload can reach your domain code in any shape. Annotate the parsed body as unknown, run it through an executable schema, and only then convert it to the domain type. Test the boundary with the payloads that actually break it: a missing field, an enum value the contract does not list yet, an extra key, and the wrong top-level type. Assert each rejection by issue path, code and a sanitised description of what was received, never by message text and never by echoing the raw body.import * as z from \"zod\", z.strictObject, z.iso.datetime(), z.treeifyError). Issue codes you may have asserted on in Zod 3 tests are not the codes Zod 4 reports; a missing enum field, for example, comes back as invalid_value. Every snippet was compiled and every test run on 2026-09-30 against TypeScript 7.0.2, Zod 4.6.5 and Vitest 5.0.2, the current releases on that date.Here is a client that compiles under strict and is wrong in two separate ways:
interface User {\n id: string;\n email: string;\n displayName: string;\n role: \"admin\" | \"editor\" | \"viewer\";\n status: \"ACTIVE\" | \"SUSPENDED\";\n}\n\nasync function getUser(id: string): Promise<User> {\n const res = await fetch(`https://api.example.test/users/${id}`);\n return (await res.json()) as User; // compiles\n}\n\nasync function getUserUnasserted(id: string): Promise<User> {\n const res = await fetch(`https://api.example.test/users/${id}`);\n return res.json(); // also compiles: Promise<any> is assignable to Promise<User>\n}\n\nfunction badge(user: User): \"green\" | \"red\" {\n switch (user.status) {\n case \"ACTIVE\":\n return \"green\";\n case \"SUSPENDED\":\n return \"red\";\n }\n}\n\nfunction roleLabel(user: User): string {\n return user.role.toUpperCase();\n}\n\n// What the service actually sent after its last deploy:\nconst fromWire = JSON.parse(\n '{\"id\":\"u_1042\",\"email\":\"a@example.test\",\"displayName\":\"Asha\",\"status\":\"ARCHIVED\"}',\n) as User;\n\nconsole.log(\"badge:\", badge(fromWire));\nconsole.log(\"role:\", roleLabel(fromWire));Run it and the first failure is silent. badge is declared to return \"green\" | \"red\" and returns undefined, because \"ARCHIVED\" matches neither case. The second failure is loud, but it is reported from roleLabel, one call away from the code that made the mistake:
badge: undefined\nfile:///app/src/wrong.ts:20\n return user.role.toUpperCase();\n ^\n\nTypeError: Cannot read properties of undefined (reading 'toUpperCase')\n at roleLabel (file:///app/src/wrong.ts:20:20)In a real application the payload is cached and rendered two screens later, and the stack trace points at a component that never touched the network. The bug is on the line with as User, where the only thing the type system recorded is that you promised.
as UserNothing about the data. The TypeScript handbook is direct about it: \"Because type assertions are removed at compile-time, there is no runtime checking associated with a type assertion. There won't be an exception or null generated if the type assertion is wrong.\" The only static rule is that an assertion must convert \"to a more specific or less specific version of a type\", which blocks \"hello\" as number and nothing else. Asserting from any always satisfies it.
And the inputs you are asserting from are any. In the TypeScript 7.0.2 standard library, JSON.parse is declared as returning any, and the DOM lib's Body interface, which Response extends, declares json(): Promise<any>. MDN describes what that promise can actually resolve to: \"anything that can be represented by JSON — an object, an array, a string, a number\". The type is honest about the runtime. Your annotation is not.
That is why getUserUnasserted is the more dangerous of the two functions above. It contains no assertion for a reviewer to question: Promise<any> is assignable to Promise<User>, so the declared return type does the asserting invisibly. A text search for as User will not find it. The typescript-eslint rule no-unsafe-return will: it disallows \"returning Promise<any> from an async function\" and is enabled by the recommended-type-checked configuration, at the cost of running lint with type information.
The usual first fix is a hand-written guard. It reads like validation:
\n\nfunction isUser(value: unknown): value is User {\n return typeof value === \"object\" && value !== null && \"id\" in value;\n}\n\nconst body: unknown = await res.json();\nif (isUser(body)) {\n body.role.toUpperCase(); // type-checks; the guard never looked at role\n}This compiles. The handbook describes the contract of a predicate: whenever the guard is called, \"TypeScript will narrow that variable to that specific type if the original type is compatible\". The compiler checks that the predicate's parameter name is real. It does not check that the function body inspected every property the type promises. A guard that tests id and nothing else narrows to a User with a guaranteed role, and you are back where as User left you, with a function call in the way.
For a two-field message that is tolerable. For a response with enums and dates, the guard and the interface drift apart silently the first time someone edits one of them. Derive the static type from the runtime check instead, so there is one definition.
\n\nThe handbook says unknown \"represents any value\" but \"it's not legal to do anything with an unknown value\". That refusal is what a boundary needs: annotating the parsed body as unknown discards the any and forces a check before use.
import * as z from \"zod\";\n\nexport const UserWire = z.object({\n id: z.string(),\n email: z.email(),\n displayName: z.string(),\n role: z.enum([\"admin\", \"editor\", \"viewer\"]),\n status: z.enum([\"ACTIVE\", \"SUSPENDED\"]),\n createdAt: z.iso.datetime(),\n});\nexport type UserWire = z.infer<typeof UserWire>;\n\n// The domain type is not the wire type: createdAt is a Date in here.\nexport interface User {\n id: string;\n email: string;\n displayName: string;\n role: UserWire[\"role\"];\n status: UserWire[\"status\"];\n createdAt: Date;\n}\n\nexport function parseUser(input: unknown): User {\n const result = UserWire.safeParse(input);\n if (!result.success) throw new UserContractError(summarize(result.error, input));\n const { createdAt, ...rest } = result.data;\n return { ...rest, createdAt: new Date(createdAt) };\n}\n\nexport async function fetchUser(id: string, fetchImpl: typeof fetch = fetch): Promise<User> {\n const res = await fetchImpl(`https://api.example.test/users/${encodeURIComponent(id)}`);\n if (!res.ok) throw new Error(`GET /users/${id} answered ${res.status}`);\n const body: unknown = await res.json();\n return parseUser(body);\n}Four details in that file carry weight.
\n\nsafeParse returns a result object instead of throwing, and Zod documents its type as a discriminated union on success, so result.data is only reachable once the check has passed. On success, Zod's basic-usage page says it \"returns a strongly-typed deep clone of the input\", which means the object your domain holds is not the object the network handed you. Later mutation of one does not reach the other.
The domain type is separate from the wire type. z.infer gives you the shape as it crosses the wire, with createdAt as a string; the application wants a Date. Keeping a UserWire and a User makes the conversion a single, testable function instead of a new Date(...) scattered across components.
z.iso.datetime() is stricter than most people expect. Zod's API reference: \"by default, no timezone offsets are allowed\", so 2026-09-01T15:30:00+05:30 is rejected unless you write z.iso.datetime({ offset: true }). Whether an offset is legal is a contract question. Look it up in the API's published description rather than loosening the schema the first time production sends one.
The non-OK branch is handled before parsing. An error body from a 500 is not a malformed user, and reporting it as a contract violation sends someone to read the wrong schema.
\n\nZod gives an object three answers to a key it was not told about. z.object strips: \"By default, unrecognized keys are stripped from the parsed result\". z.strictObject produces a schema \"that throws an error when unknown keys are found\". z.looseObject lets them \"pass through\".
The right answer depends on where the parse runs. In the production client, stripping is the default worth keeping: when the provider ships an additive field, your page keeps working, and a field you never declared, such as an internal hash someone accidentally serialised, never reaches your store or your logs. A strict parse in production turns every additive deploy on the provider side into an outage on yours.
\n\nIn the test suite you want the opposite, because an undeclared key is information. Build the strict variant from the same shape so the two cannot drift:
\n\n// Production parse: undeclared keys are dropped from result.data.\nUserWire.parse({ ...payload, passwordHash: \"…\" }); // no passwordHash in the output\n\n// Contract suite: same shape, but an undeclared key is an issue with a name.\nexport const UserWireStrict = z.strictObject(UserWire.shape);One trap sits next to this decision. If you export the stripping schema with z.toJSONSchema(UserWire) to compare it with a published contract, the output includes \"additionalProperties\": false. Zod's JSON Schema page explains why: by default the conversion \"represents the output type\", and a stripped output has no extra keys. Pass { io: \"input\" } and the line disappears. Diff the input form against the contract, or the export looks stricter than the parse that actually runs.
This is the detail that makes naive assertions pass for the wrong reason. Parse the three broken payloads with Zod 4.6.5 and look at the raw issues:
\n\n// role absent\n[{ \"code\": \"invalid_value\", \"values\": [\"admin\", \"editor\", \"viewer\"], \"path\": [\"role\"],\n \"message\": \"Invalid option: expected one of \\\"admin\\\"|\\\"editor\\\"|\\\"viewer\\\"\" }]\n\n// status: \"ARCHIVED\"\n[{ \"code\": \"invalid_value\", \"values\": [\"ACTIVE\", \"SUSPENDED\"], \"path\": [\"status\"],\n \"message\": \"Invalid option: expected one of \\\"ACTIVE\\\"|\\\"SUSPENDED\\\"\" }]\n\n// displayName absent (a plain string field, for contrast)\n[{ \"expected\": \"string\", \"code\": \"invalid_type\", \"path\": [\"displayName\"],\n \"message\": \"Invalid input: expected string, received undefined\" }]An absent string field gets invalid_type with expected: \"string\". An absent enum field gets invalid_value, the same code as an enum field holding a value the contract does not list, and neither carries an expected property. A test asserting { path: [\"role\"], code: \"invalid_value\" } cannot tell \"the v1 provider never sends role\" from \"the provider started sending role: owner\". Those are different incidents with different owners.
The issue also does not tell you what was received. That is deliberate: Zod's error-customisation page says \"By default, Zod does not include input data in issues. This is to prevent unintentional logging of potentially sensitive input data\", and the reportInput flag turns it back on. Rather than turning it on, compute a description of what sat at the issue's path yourself, and choose what is safe to show:
export type IssueSummary = { path: string; code: string; expected?: string; received: string };\n\n// Fields whose values are vocabulary from the contract, never user data.\nconst ECHO_SAFE = new Set([\"role\", \"status\"]);\n\nfunction receivedAt(input: unknown, path: PropertyKey[]): string {\n let cur: unknown = input;\n for (const key of path) {\n if (cur === null || typeof cur !== \"object\" || !(key in cur)) return \"missing\";\n cur = (cur as Record<PropertyKey, unknown>)[key];\n }\n if (typeof cur === \"string\" && ECHO_SAFE.has(String(path.at(-1)))) return JSON.stringify(cur);\n if (cur === null) return \"null\";\n return Array.isArray(cur) ? \"array\" : typeof cur;\n}\n\nexport function summarize(error: z.ZodError, input: unknown): IssueSummary[] {\n return error.issues.map((issue) => ({\n path: issue.path.join(\".\") || \"(root)\",\n code: issue.code,\n ...(\"expected\" in issue ? { expected: String(issue.expected) } : {}),\n received: receivedAt(input, issue.path),\n }));\n}\n\nexport class UserContractError extends Error {\n readonly issues: IssueSummary[];\n constructor(issues: IssueSummary[]) {\n super(`user payload broke the contract: ${JSON.stringify(issues)}`);\n this.name = \"UserContractError\";\n this.issues = issues;\n }\n}For most fields the summary records only the kind: missing, null, array or a typeof result. For fields whose values are vocabulary defined by the contract, the value itself is the diagnosis, so those are allowlisted by name. An email address never qualifies. Here is the error a version-skewed payload produces through fetchUser:
UserContractError: user payload broke the contract: [{\"path\":\"role\",\"code\":\"invalid_value\",\"received\":\"missing\"},{\"path\":\"status\",\"code\":\"invalid_value\",\"received\":\"\\\"ARCHIVED\\\"\"}]That line is the evidence a boundary failure should leave: which path, which rule, what arrived, and no personal data to scrub from the log aggregator afterwards.
\n\nimport { describe, expect, test } from \"vitest\";\nimport { UserContractError, UserWire, UserWireStrict, fetchUser, parseUser, summarize } from \"./user\";\n\nconst accepted = {\n id: \"u_1042\",\n email: \"asha.k@example.test\",\n displayName: \"Asha K\",\n role: \"editor\",\n status: \"ACTIVE\",\n createdAt: \"2026-09-01T10:00:00Z\",\n} satisfies UserWire;\n\nconst without = <K extends keyof typeof accepted>(key: K) => {\n const { [key]: _dropped, ...rest } = accepted;\n return rest;\n};\n\ndescribe(\"user payload at the boundary\", () => {\n test(\"accepts the published shape and converts createdAt\", () => {\n const user = parseUser(accepted);\n expect(user.createdAt).toBeInstanceOf(Date);\n expect(user.role).toBe(\"editor\");\n });\n\n test(\"strips an undeclared key instead of passing it into the domain\", () => {\n const user = parseUser({ ...accepted, passwordHash: \"x\" });\n expect(user).not.toHaveProperty(\"passwordHash\");\n });\n\n test.each([\n { name: \"role missing (v1 provider)\", input: without(\"role\"), path: \"role\", code: \"invalid_value\", received: \"missing\" },\n { name: \"status added upstream\", input: { ...accepted, status: \"ARCHIVED\" }, path: \"status\", code: \"invalid_value\", received: '\"ARCHIVED\"' },\n { name: \"displayName missing\", input: without(\"displayName\"), path: \"displayName\", code: \"invalid_type\", received: \"missing\" },\n { name: \"createdAt with an offset\", input: { ...accepted, createdAt: \"2026-09-01T15:30:00+05:30\" }, path: \"createdAt\", code: \"invalid_format\", received: \"string\" },\n { name: \"array instead of object\", input: [accepted], path: \"(root)\", code: \"invalid_type\", received: \"array\" },\n ])(\"rejects $name\", ({ input, path, code, received }) => {\n const result = UserWire.safeParse(input);\n expect.assert(!result.success);\n expect(summarize(result.error, input)).toEqual([expect.objectContaining({ path, code, received })]);\n });\n\n test(\"the strict variant reports an added key by name\", () => {\n const result = UserWireStrict.safeParse({ ...accepted, tenantId: \"t_9\" });\n expect.assert(!result.success);\n expect(result.error.issues).toMatchObject([{ code: \"unrecognized_keys\", keys: [\"tenantId\"], path: [] }]);\n });\n\n test(\"a contract failure from fetch carries no field values\", async () => {\n const stub = async () => Response.json({ ...accepted, role: undefined, status: \"ARCHIVED\" });\n const failure = await fetchUser(\"u_1042\", stub).catch((e: unknown) => e);\n expect(failure).toBeInstanceOf(UserContractError);\n expect(String((failure as Error).message)).not.toContain(accepted.email);\n expect((failure as UserContractError).issues.map((i) => i.path)).toEqual([\"role\", \"status\"]);\n });\n});The accepted fixture uses satisfies, which the TypeScript 4.9 release notes introduced to \"validate that the type of an expression matches some type, without changing the resulting type of that expression\". A typo in the fixture fails compilation, and the literal types survive. It checks your fixture against your own schema's type, which is all it can do: satisfies is as compile-time as as, and it knows nothing about what the server sends.
The negative fixtures are derived from the accepted one with a single change each. A rejected payload that differs from the good one in three ways passes even if two of the rules are broken, because the third still trips.
\n\nThe test.each rows are objects, and the title uses $name, which Vitest's API reference documents as access to \"object properties and array elements with $ prefix\". Choose that property carefully. Interpolate the payload itself and Vitest prints it into the test name:
// Don't: the whole fixture lands in the test name, and from there in every report.\ntest.each([{ input: { email: \"asha.k@example.test\", role: \"owner\" } }])(\"rejects $input\", ...);\n// ✓ rejects { email: 'asha.k@example.test', …(1) }Test names travel into CI logs, JUnit XML and dashboards with a far wider audience than the fixture file. Name the case; keep the data in the body.
\n\nexpect.assert(!result.success) is doing type work as well as test work. Vitest re-exports Chai's assert as expect.assert and notes this is \"especially useful if you need to narrow down the type, since expect.to* methods do not support that\". After it, result.error is typed without a non-null assertion.
None of the assertions mention a message. The regular zod package loads its English locale automatically, and messages can be replaced per schema with the error parameter, so message text is presentation that someone may change for a good reason. The path, the code and your received-kind description are the contract.
The strict-variant test uses toMatchObject, which checks \"a subset of the properties of an object\" but, given an array, also its length. That pins exactly one issue naming tenantId and ignores its message.
A language model will turn three example responses into a Zod schema in seconds, and for a wide response that saves real typing. What it cannot know is which observed facts are rules; the published contract and the domain owner decide which fields are required and which variants are accepted. Every key present in all the samples comes back required. Every enum comes back as the set of values that happened to appear, so a status that exists in the contract but not in the samples is rejected, and the sample set decides what production accepts. Fields that are nullable but were never null in the samples are drafted as plain strings.
\n\nTreat the draft the way you would treat one generated from a single response in the JSON Schema generator: a starting point whose required list and enum values you check against the published contract line by line. A practical check is to export the draft with z.toJSONSchema(schema, { io: \"input\" }), then compare its required array and enum lists with the OpenAPI component in the JSON Diff tool. Going the other way, Zod 4 has z.fromJSONSchema(), but its own documentation calls it experimental and \"not considered part of Zod's stable API\", which is a poor property for code that gates production traffic.
Every parse walks the whole value and, on success, clones it. On a hot path that handles thousands of messages a second, that is measurable. Zod 4.6 adds .validate(), which \"returns a boolean, never builds an error, and acts as a type guard on the schema's input type\", and which the docs put at up to 16x faster than .safeParse().success on invalid input. It fits filtering. It does not fit a boundary where you need the evidence above, because it gives you none, and it narrows to the input type, so transformations have not run.
Do not validate values your own process constructed. A function receiving a User from another module in the same build is inside the boundary; re-parsing it adds cost and a second place to update. The boundaries worth a schema are the places data arrives from something your compiler never saw: HTTP responses, localStorage and sessionStorage (which hand you strings you will JSON.parse into any), postMessage payloads, environment variables, queue messages, and the arguments a model passes to a tool you exposed to it.
Moving the failure earlier has its own cost: with a strict enum, a provider that adds ARCHIVED breaks your user page instead of mis-rendering one badge. That is usually the right trade, but decide it per field, and where a new value should degrade gracefully, model that in the schema and test it.
Find the places where an untyped parse is asserted straight into a domain type:
\n\n# Assertions stacked directly on an untyped parse\ngrep -rnE --include='*.ts' --include='*.tsx' \\\n '(\\.json\\(\\)\\)?|JSON\\.parse\\([^)]*\\)) as [A-Z]' srcThat misses the unasserted form, where a declared return type absorbs Promise<any>, so also enable @typescript-eslint/no-unsafe-return if your lint already runs with type information.
Pick the endpoint whose failures would hurt most. Write its schema from the published contract, not from a captured response. Change the fetch to annotate the body as unknown and return parseUser(body) or its equivalent. Then add five tests: the accepted payload, one missing required field, one enum value the contract does not list, one undeclared key against the strict variant, and one wrong top-level type.
The evidence to keep is the summary array for each rejected case, committed as the expected value in the test. When the contract changes, the diff in that array is the review: which path, which code, and whether the new behaviour is the one the contract owner meant.
\n\nOnly if the generator emits runtime validators, and you should confirm that by reading the generated code, not its README. Generated interfaces are the same kind of promise as a hand-written interface User: correct when the server matches the spec it was generated from, and silent when a deploy on either side skews them.
parse or safeParse?parse throws a ZodError; safeParse returns the result so you can build your own error first. Use safeParse where you want to control what the thrown error contains, as parseUser does, so the raw issue list and anything a future reportInput setting adds never travel further than the boundary.
Only if the contract says clients must tolerate new values. If it does, write that rule into the schema deliberately and give it a test row of its own, so the tolerance is visible in review. If it does not, rejecting ARCHIVED is correct, and the failing test is how you find out the provider moved first.